Notice

This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

Introduction and goals

This chapter gives you an overview about the goals of the service, in which context the service runs and which stakeholders are involved.

Requirements overview

What is the purpose of the Trace-X application

  • Empower all companies from SMEs to large OEMs to participate in parts traceability with an open-source solution to easily take part in the Catena-X traceability use case.

  • It is a standalone application which can be self-hosted.

  • Display the relations of the automotive value chain based on a standardized IT model.

  • Overview and transparency across the supplier network enable faster intervention based on recorded events in the supply chain.

  • Notifications & Messages regarding quality-related incidents and a tool for inspecting the supply chain.

Essential features

  • List, view and publish manufactured parts based on BoM AsBuild

  • List, view and publish planned parts based on BoM AsPlanned

  • Filter and search functionality on part views

  • Show detailed information on manufactured parts from AAS description assets and aspects

  • Uses submodels SerialPart, Batch, JustInSequence and PartAsPlanned

  • List and view supplier parts (SingleLevelBomAsBuilt) based on BoM AsBuilt lifecycle

  • List and view customer parts (SingleLevelUsageAsBuilt) based on BoM AsBuilt lifecycle

  • View parts and parts relations in a visualized parts tree

  • Send and receive top-down notifications (quality investigations) along the supply chain

  • Compliance with Catena-X guidelines

Quality goals

The following table entries define overall Trace-X quality goals. The order of topics does not imply a priority of the quality goals.

Quality goal Motivation and description

Running reference application for Catena-X traceability

Consume traceability data, visualize it in a state-of-the-art frontend to the user and enable the exchange of notifications.

Accessible and easy to use

Enable SMEs to large enterprises.

Cloud agnostic solution

Trace-X is built as a reference architecture and able to be run on different cloud solutions. It uses Helm charts so that it can easily be deployed on different systems.

Trustworthy application

Trace-X uses the Catena-X standards as a basis to fulfill the interoperability (with commercial as well as other solutions) and data sovereignty requirements.

Application reliability

The Trace-X architecture is set up so that provided part tree structures are consumed, aggregated and utilized to enable quality related actions such as notifications along the supply chain on which the costumers can rely.

Usability and user experience

Trace-X is aligned with the overarching UUX guidelines. This ensures ease of use for the user as well as a good user experience.

Security

Static Application Security Testing (SAST) and Dynamic Application Security Testing (DAST) are executed automatically and regularly. Findings are recorded and mitigated.

Stakeholder

The following table presents the stakeholders of Trace-X and their respective interests.

Who Matters and concern

Software developer

  • Make an impact on Catena-X by participating in open-source software.

  • Example implementation for own use cases and applications.

Operating environments

  • Use Trace-X as a basis for industrialization.

  • Example implementation for own business applications, further features and fast ramp up.

Catena-X partners

  • Take part in traceability use case.

  • See relationships in the value chain.

  • React on quality issues with standardized actions and notifications.

Larger OEMs / tiers

  • Want to use this implementation for further development and integration into their system landscape.

SMEs

  • Need a solution to view data provided into the Catena-X network.

  • Act in a standardized way with partners within CX.

Architecture constraints

Technical constraints

Name Description

Interoperability

Trace-X must use the EDC together with Catena-X approved data models to guarantee interoperability between participants.

Data sovereignty

Data owners and data consumers have to use usage policies for offering, consuming and therefore transferring data.

Kubernetes for container orchestration

Catena-X requires the application to run in a Kubernetes environment, deployed via Helm charts.

Catena-X UUX guidance (CX style guide)

The frontend of Trace-X follows Catena-X-wide UUX consistency according to the CX style guide.

Organizational constraints

Name Description

Schedule

Start of development in July 2022. Further development in alignment with the foundation of the Catena-X Automotive Network e.V. requirements and timeline.

Process model

Iterative and incremental. The SAFe framework is used to align with Catena-X services, prerequisites, components and requirements to be Catena-X compatible.

Catena-X services / requirements

Trace-X needs to be Catena-X compliant and the application has to follow the CX standards as well as interact with the core services and components.

Release as open source

The source code - at least partially - is made available as open source and can be found in GitHub Catena-X ng as well as in Eclipse Tractus-X.

Technology Readiness Level (TRL) for products developed within the CX consortia

As Trace-X is a reference implementation, the Technology Readiness Level (TRL) must not be above TRL 8.

Political constraints

Name Description

Open source

FOSS licenses approved by the Eclipse foundation have to be used.

Development conventions

Name Description

Architecture documentation

Architectural documentation of Trace-X reference application in arc42-template terminology and structure.

Language

The project language is English to ensure the best possible accessibility for all participants. Therefore, classes, methods etc. are named in English and the documentation is written in English.

Test coverage

More than 80% of the complete source code has to be test covered.

System scope and context

Trace-X is an end-user application to visualize and utilize data provided to the Catena-X network. This includes the traceability of manufactured parts and batches as well as the shipped and supplied components. To utilize the CX open ecosystem, it is necessary to exchange information on serialized parts and batches with supply chain partners in a standardized, data-sovereign and interoperable way. This section describes the environment of Trace-X, its intended users and which systems and components it interacts with.

Business context

Trace-X exchanges data with any other traceability applications within the CX ecosystem. This is implemented by integrating the service into the CX network and the usage of required central components and services provided by CX.

business context

User

Trace-X can be deployed, hosted and run by every party that is part of the Catena-X network. They need to be registered, have a BPN and a technical user as well as provide valid credentials. An end-user in Trace-X can have roles provided by the CX portal (user, supervisor, admin).

IRS

The Item Relationship Service is the component that is used by Trace-X to fetch data chains from Catena-X network. Data that is provided by IRS gets extracted, aggregated, transformed and is used for further actions in Trace-X. Further information can be found in the IRS architecture documentation (arc42).

Catena-X network

Trace-X and IRS are retrieving necessary information and data from the Catena-X network (users, digital twins, aspects, submodels, business partner information). If CX services are unavailable, Trace-X will not be able to perform most of its work.

Any other traceability app

Trace-X interacts with any other traceability app using the CX standards. This enables sovereign data exchange as well as receiving and sending notifications to interact between different parties.

Technical context

Component overview

Trace-X API

We provide a REST API that is consumed by Trace-X frontend in order to deliver Trace-X related features such as quality investigations or asset chain visibility. Since the Trace-X component is the very last component in the Catena-X ecosystem we are mostly dependent on the other services and theirs APIs in other to deliver desired functionalities. The development of the services is not a part of the Trace-X application and each of the system that we utilize exposes a REST API that we consume and interact with directly.

Trace-X is a Spring Boot based application and is secured with the OpenID connector provider Keycloak and OAuth2. This means for the companies that utilize the Trace-X component, it is required to obtain a technical user to be authorized to get access to the external components within the Catena-X ecosystem.

In order to use the Trace-X frontend with the Trace-X backend, users need to authenticate themselves in order to be authorized to get access to the Trace-X. In the frontend UI users provide valid credentials and the system generates a bearer token that it gets from Keycloak and attaches it to the HTTP header parameter Authorization. Once a user is authorized and has a proper role in the Trace-X backend, the backend delegates HTTP calls to specific services on their behalf as technical user in order to fulfill specific functionalities.

[Outdated] Registry API
technical context registry

Trace-X acts as a consumer of the asset administration shell registry component. Trace-X contains a restful client (REST template) that builds a REST call to the mentioned digital twin registry API based on its known URL (the AAS registry URL is configurable in Trace-X). Requests contain 'assetIds' provided by the component during asset synchronization. Like described in the above section, the security aspect is required in order to achieve a REST call against the AAS Registry. As a response, Trace-X gets the corresponding shells and shell descriptors utilized later for asset synchronization. The HTTP(s) transport protocol is used for the REST call communication.

IRS API
technical context irs

Trace-X acts as a consumer of the IRS component. Trace-X contains a restful client (REST template) that build a REST call to the mentioned IRS API based on its known URL (the IRS URL is configurable in Trace-X). The request contains details required to start an IRS fetch job provided by the component during asset synchronization. Like described in the above section, the security aspect is required in order to achieve a REST call against the IRS. As a response, Trace-X gets the created job id and periodically pulls for the job details that contains assets that will be uploaded to the system. As mentioned above, the transport protocol HTTP(S) is used for the REST call communication.

[Outdated] Portal API
technical context portal

Trace-X acts as a consumer of the portal component. Trace-X contains a restful client (REST template) that builds a REST call to the mentioned Portal API based on its known URL (the Portal URL is configurable in Trace-X). The portal is used to authenticate users and requests against the backend. As mentioned above, the transport protocol HTTP(S) is used for the REST call communication.

[Outdated] EDC API
technical context edc

The Trace-X acts as a consumer and provider of the EDC component. In Trace-X we communicate with the EDC directly only for the sake of fulfilling the quality notification functionality. Specific use cases can be viewed in the Runtime view section. For these purposes the integrated EDC clients in Trace-X are responsible for creating restful requests to the EDC component. As mentioned above, the transport protocol HTTP(S) is used for the REST call communication.

Solution strategy

This section contains a summarized architectural overview, a comparison of the most important goals and the corresponding solution approaches.

Introduction

Following table describes the quality goals of Trace-X (see chapter quality goals) and their matching solution approaches.

Quality goal Matching approaches in the solution

Running reference application for Catena-X traceability

  • Published open-source, Trace-X application can be used as a reference by anyone.

Accessible and easy to use

  • Established programming languages are used.

  • Backend written in Java.

  • Frontend written in Typescript based on the Angular framework.

Cloud agnostic solution

  • Helm charts to support the deployment of the application in a Kubernetes environment.

Application reliability

  • Data source is the Catena-X network. Data is fetched directly from the data owner using the IRS and the digital twin registry of CX.

  • Trace-X can be hosted decentralized since it is an open-source reference implementation.

Security

  • Static Application Security Testing (SAST) and Dynamic Application Security Testing (DAST) are executed automatically and regularly with tools as part of the pipeline.

Technology

Trace-X is developed using Java and the Spring Boot framework for the backend and Typescript based on the Angular framework for the frontend. This decision was taken due to the support of the frameworks as well as technical knowledge of the team members.

The application can be hosted using Docker and Kubernetes. This is commonly used and widespread. With this the application has no vendor lock in regarding the hosting provider.

The communication between frontend and backend is done using REST APIs. This is the standard method in the Catena-X landscape and makes the application components easy to use for any third party client.

For the database PostgreSQL is used.

Structure

Trace-X is divided into two components: Frontend and backend. It roughly can be broken down into the following parts:

  • Asset controllers to get asset information

  • Dashboard controller to get dashboard related summed up information

  • Registry controller to fetch assets from the Digital Twin Registry

  • Notification controller to get notification information and create EDC notification offers

  • Submodel controller for providing asset data functionality

  • Import controller for importing Trace-X data for data provisioning

  • Contract controller to get information about contract agreements

  • EDC controller to retrieve notifications

  • IRS callback controller to retrieve asynchronous jobs completed by IRS

  • Policy controller to retrieve information about policies

  • BPN controller to retrieve information about business partners

The backend does a request to the Digital Twin Registry utilizing the registry controller. Extracted data from the response is made available through the asset controller and the dashboard controller to the frontend.

Building block view

Blackbox overall system

Component diagram

whitebox overview

Component description

Components Description

IRS

The IRS consumes relationship information across the CX-network and builds the graph view.

EDC consumer

The EDC consumer component is there to fulfill the GAIA-X and IDSA-data sovereignty principles. The EDC consumer is composed of a control plane and a data plane.

EDC provider

The EDC provider component connects with EDC consumer component and forms the endpoint for the actual exchange of data. It handles automatic contract negotiation and the subsequent exchange of data assets for connected applications.

Submodel server

The submodel server offers endpoints for requesting the submodel aspects.

Level 1

Component diagram

level 1

Component description

Components Description

Trace-X

Trace-X is a system allowing the user to review the parts / assets catalog and send / receive quality notifications related to those parts.

Trace-X API

The Trace-X API is the interface through which the data consumer is communicating.

AssetsController

The AssetsController provides a REST interface for retrieving asset information.

DashboardController

The DashboardController provides a REST interface for retrieving overall statistics displayed on the dashboard screen.

RegistryController

The RegistryController provides a REST interface for retrieving data from the assets registry.

ImportController

The ImportController provides a REST interface for importing assets and publishing them in the Catena-X network.

AssetRepository

The AssetRepository is a component responsible for storing and getting assets from the database.

BPNRepository

The BPNRepository is a component which stores BPN → company name mappings.

NotificationsRepository

The NotificationsRepository is a component responsible for storing the status and data of sent and received notifications.

Database

The database is a place for storing assets, relations and notifications.

Runtime view

This section describes the different functionalities of the Trace-X application.

Assets

Scenario 1: Return assets

This section describes what happens when users list stored assets. In this example, the user requests as-built assets. The same can be done with as-planned assets.

return all assets
Overview

When a user requests stored assets, Trace-X checks if the user has an adequate role ('ROLE_ADMIN', 'ROLE_SUPERVISOR', 'ROLE_USER'). If yes, then the endpoint returns a pageable result of assets.

The returned result can be empty if no suitable asset has been found.

Scenario 2: Return specific assets

This section describes what happens when users search for a specific asset. This example shows the request of one as-built asset. The same can be done with as-planned assets.

return specific assets
Overview

When a user requests a specific asset, Trace-X checks if the user has an adequate role ('ROLE_ADMIN', 'ROLE_SUPERVISOR', 'ROLE_USER'). If yes, then the endpoint returns the asset for the given assetId, if it is found.

If no asset has been found for the given ID, an AssetNotFoundException is thrown.

Notifications

Receive quality notification

This sequence diagram describes the process of receiving a quality notification from another traceability partner:

business context quality investigation
Overview

The EDC is utilized to transmit data between sender and receiver for both sending and receiving notifications. To be able to receive notifications by a partner you need to

  • Create a notification endpoint for qualitynotifications/receive

  • Create EDC assets

  • Create EDC usage policies

  • Create EDC contract definitions

Trace-X implements a functionality to create assets and their corresponding policies in the admin panel.

With the notification asset it is possible to enable EDC contract negotiation and EDC data transfer based on access policies defined. Only if the sender is able to find the asset in the catalog offer and perform a successful contract negotiation there will be the possibility to send a notification to the specified http endpoint on the receiver side.

Send quality notification

This sequence diagram describes the process of sending a quality notification between traceability applications:

business context quality investigation send
Overview

The EDC is utilized to transmit data between sender and receiver for both sending and receiving notifications. To be able to send notifications to a partner you need to

  • Create a notification endpoint for qualitynotifications/send

  • Create EDC assets

  • Create EDC usage policies

  • Create EDC contract definitions

Trace-X implements a functionality to create assets and their corresponding policies in the admin panel.

With the notification asset it is possible to enable EDC contract negotiation and EDC data transfer process so that the quality investigation can be sent by the sender.

Data consumption

This sequence diagram describes the process of fetching data from the DTR and the Catena-X ecosystem:

business context data consumption

Overview

Data is fetched by a Trace-X instance using the Digital Twin Registry (DTR), Item Relationship Service (IRS) and Trace-X consumer EDC. For digital twins the Asset Administration Shell (AAS) standard is used. For fetching data with Trace-X a Digital Twin Registry and an IRS instance are required. Data should represent parts, supplier and customer parts, part trees / part relations.

Data provisioning

The following sequence diagrams describe the process of importing data from a Trace-X dataformat:

Module 1

Data will be imported by the Trace-X frontend into the Trace-X backend and will be persisted as an asset in a transient state. The raw data which is needed for the shared services (DTR / EDC) will be persisted as well.

business context data provisioning 1

Module 2

The frontend is able to select assets and publish / synchronize them with the shared services DTR / EDC / submodel API.

business context data provisioning 2

Module 3

The backend is able to persist the data in the DTR / EDC and enables the IRS to resolve assets.

business context data provisioning 3

Scenario 1: Receive import report

This section describes what happens when the user wants to get a report of the imported assets associated with a importJobId. In this example, the user requests an import report.

import report receive
Overview

When a user requests an import report, Trace-X checks if the user has an adequate role ('ROLE_ADMIN', 'ROLE_SUPERVISOR'). If yes, the endpoint returns the import report of the given importJobId.

If the importJobId is not known to Trace-X, an HTTP 404 error is returned.

Scenario 2: Publish assets

This section describes the user interaction when publishing assets

publish assets
Overview

When a user publishes assets, Trace-X checks if the user has an adequate role ('ROLE_ADMIN'). If yes, the endpoint starts to publish assets to the network.

Scenario 3: Publish assets - error on EDC or DTR

This section describes the user interaction when publishing assets fails due to an EDC or DTR error (for example when the services are unavailable).

publish assets error
Overview

When a user publishes assets, Trace-X checks if the user has an adequate role ('ROLE_ADMIN'). If yes, the endpoint starts to publish assets to network. If any of the required services are not available or return an error response upon executing, the included assets are set to ERROR state and the user can retry publishing them at any time when services are available again.

Data sovereignty

Scenario 1: Return asset contract agreements

This section describes the functionality and behavior when a user requests contract agreements from Trace-X via the Trace-X contracts API (/contracts).

return all contracts
Overview

In case a user requests contract agreements, Trace-X checks if the user has required roles ('ROLE_ADMIN', 'ROLE_SUPERVISOR'). If yes, the requested assets will be mapped to the related contract agreement ID. These contract agreement IDs will be then requested on EDC side via POST (/management/v2/contractagreements/request) and GET (/management/v2/contractagreements/{ContractAgreementId}/negotiation) to get the relevant information.

The contract information is then returned by the endpoint as a pageable result.

If no asset IDs are provided in the request, 50 contract agreements are returned by default.

Policy management

To ensure data sovereignty within Trace-X, companies can create policies with constraints to ensure that their data is only shared with companies that match their requirements.

Policies will be used by the EDC to initiate contract negotiations. During the negotiation the EDC will compare the policies of both companies. Only if both policies are valid and the included constraints match, the data will be shared. This applies for sending and receiving of notifications and parts.

After deploying Trace-X, no policies are defined for any BPNs yet. Instead, Trace-X will set up default policies. This ensures that the basic functionality of Trace-X works. However, to be sure that data is shared only with companies that match one’s requirements, an administrator must set up policies before sending and receiving data.

The policies used for sending and receiving notifications and parts have an identical data format, so they can be used for each process interchangeably. The processes itself are different and will be explained in this section.

Policy Types

The EDC connector MUST provide a possibility to restrict the access of a data asset to specific business partners by attribute(s), e.g. represented as a VC. The connector MUST restrict the data usage to partners and purposes for a specific use case.

There are two policy types used.

  • Access

  • Usage

As specified by the Dataspace Protocol one data asset MUST refer to at least one usage policy, expressed in ODRL. For additional information refer to the Connector KIT

Policies for sending and receiving parts
data sovereignty publish assets

1,2,3,4

Policies can be created by user with role 'Admin' at any time in the administration section of Trace-X. The policy is created to later used for publishing parts in the current company context. Policies are stored in the PolicyStore which is a shared component used by Trace-X [A] and Item Relationship Service (IRS) for storing usage and access policies.

5,6

User with role 'Admin' imports assets in the administration section of Trace-X [A]. Parts can be imported at any time in the parts section of Trace-X. They will be stored locally at first. Testdata for asset import

7,8,9

User with role 'Admin' selects parts in transient state in application and publishes them. The user must choose the policy that is used for the contract negotiation of the selected parts.

10,11

The parts are created in the EDC. (POST /v3/assets)

12,13

In case the PolicyDefinition does not exist yet, a new PolicyDefinition is created in the EDC [A].

14,15

A contractDefinition is created using the provided policyDefinition.

16,17

Each part is created as a Asset Administration Shell Descriptor in the Digital Twin Registry (DTR). This holds all the data of the part including the globalAssetId.

18,19,20,21

Policies can be created by user with role 'Admin' at any time in the administration section of Trace-X. When synchronizing parts, the respective policies for connected BPNLs will be used.

22

Trace-X [B] wants to synchronize parts and retrieve available ones from connected BPNs. In this case Trace-X [A] and Trace-X [B] have an established connection.

23,24

Trace-X [B] requests all Asset Administration Shell Descriptors in the DTR of Trace-X [A].

25

The globalAssetIds are extracted from the Shell Descriptors.

26

For part synchronization a job is started in the IRS using the globalAssetIds from the previous step.

27,28

IRS requests the catalogOffer for all globalAssetsIds.

29,30

IRS requests policies defined for the BPNL of Trace-X [A] in the PolicyStore of Trace-X [B].

31

Now that the IRS has all the relevant policies of both companies, it can start comparing the linked policy in the catalogOffer of each part to the policy list of Trace-X [B]. This works by comparing the included constraints logically.

32,33,34,35

If the policy of the part matches with any policy of Trace-X [A], a contract agreement is created for both Trace-X [A] and Trace-X [B]. It can be viewed in the administration section of Trace-X and documents the data exchange.

ref import part data

Now that the contract negotiation was successful, the part data can be imported. This process is documented in the data consumption section.

36,37

In case the policy does not match, IRS creates a tombstone and sends a job response to Trace-X [B].

38

IRS responds to the Trace-X [B] instance after completing job processing. The contractAgreementId for the asset is available in the job response.

It’s possible to publish parts with different policies. For this, the user must only publish a limited selection of parts for which he can select a policy. For parts that must be published with different policies, the user can repeat the process.

Note: For more detailed information concerning the functionality of IRS please refer to the IRS documentation

[Work-in-progress] The user may also choose parts that have already been published - they can be republished with a different policy. The process for this is identical to the regular publishing process.

Policies for sending and receiving notifications
data sovereignty notifications

1

Policies can be created by administrators at any time in the administration section of Trace-X. In order for policies to be used for notifications the administrator must pay attention to the BPN selection of the policies, as Trace-X will choose notification policies based on that.

2

The user sends a notification to a connected BPN.

3

First, Trace-X checks the configured policies for any valid (not expired) policies that have the BPN of the receiver in their BPN selection. There can only be one valid policy for each BPN.

4

Trace-X takes the appropriate policyDefinition.

5

Trace-X requests the catalog of the receiver BPN from their EDC. The catalog contains all policies of the BPN including the policies they use for sending and receiving policies.

6

The receiver EDC returns the catalog.

7

Trace-X extracts the required policy definition for receiving notifications from the catalog. If the receiving BPN has multiple valid ones, they all will be extracted in a list.

8

Trace-X compares the extracted policies with its own policy definition. This works by comparing the included constraints logically.

9, 10

If any of the policies match, a contract agreement is created and shared with the receiving EDC and the EDC of the sender. It can be viewed in the administration section of Trace-X.

11

Finally, the notification will be sent to the receiving EDC.

12

If no policies match, an error will be returned to the user.
No policies defined for receiver when sending notifications
data sovereignty notifications policy change

If no policies are configured for the receiving BPN and a notification is sent to that BPN, the default policy of Trace-X is used as a backup. If the default policy is accepted by the receiving BPN, the process can continue as normally and the notification can be sent. When the policy does not match and the notification can’t be sent, an administrator can create policies for the receiving BPN. Then the notification can be resent and will use the new policy.

Expired policy when sending notifications
data sovereignty expired policy

Policies always have an expiration time defined by the 'validUntil' timestamp. When a notification is sent and there are policies configured for the selected BPN with an expiration time in the past, Trace-X will throw an error. In that case, an administrator must update or recreate the policy. Then the policy can be resent.

Testing policies

In order to test the functionality of policies, an administrator can create a policy with test constraints for connected BPNs. When sending notifications to that BPN, the process should be blocked.

To fix it, the administrator either has to replace the policy with a valid policy or the connected BPN can create an identical policy with the same test constraints. Sending the notification will work after this was done.

The same applies for sending and receiving parts only then the user must choose the created test policy manually.

An example testing process will be described here with two companies Trace-X A and Trace-X B:

Step 1

In the initial state of Trace-X, only the default policy exists:

step 1

The catalog offer contains the policy definition of the default policy:

step 1 1

In this state both companies can send notifications to each other.

Step 2

In this example Trace-X B creates a new policy:

step 2
step 2 1

Once created, the catalog offer will be updated using this policy:

step 2 2
Step 3

Since the catalog offer of Trace-X B was updated, Trace-X A won’t be able to send notifications to Trace-X B anymore:

step 3

Trace-X A will take its own default policy and compare it to the catalog offer provided by Trace-X B, which will result in a mismatch.

Step 4

Since Trace-X B has no policy defined for Trace-X A’s BPN, it will compare its own default policy with the catalog offer provided Trace-X A which is identical to the default policy. So Trace-X B can still send notifications to Trace-X A:

step 4
Step 5

Now Trace-X A can create a new policy using the same constraints as Trace-X B’s policy:

step 5
step 5 1

This policy will now be used when sending notifications to Trace-X B. Trace-X A’s catalog offer is unchanged.

Step 6

Trace-X A can now send notifications to Trace-X B again, since the policy matches with the provided catalog offer:

step 6

Policies

Overview

Scenario 1: Startup interaction with the IRS policy store

The Trace-X instance defines a constraint which is required for data consumption and provisioning. Trace-X retrieves all policies from the IRS and validates if one of the policies contains the required constraint given by Trace-X. If a policy with the constraint exists and is valid, the process ends. If the policy is not valid, it will create one with the given constraint.

This sequence diagram describes the process of retrieving or creating policies from the IRS policy store based on the constraint given by Trace-X:

policy startup configuration
Scenario 2: Startup interaction with EDC

The Trace-X instance uses the policy which includes the defined constraint and transforms it into a valid EDC policy request. The EDC policy request will be used for creating a policy for the required notification contracts.

This sequence diagram describes the process of retrieving the correct policy by IRS policy store based on the constraint given by Trace-X and reuses it for creating an EDC policy.

policy startup notification contract
Scenario 3: Provisioning of notifications

The Trace-X instance uses the policy which includes the defined constraint for validation of catalog offers by the receiver EDC.

This sequence diagram describes the process of how the policy with the defined constraint will be used for validation of the catalog offers from the receiver EDC:

policy notifications
Scenario 4: Provisioning of assets

The Trace-X instance uses the policy which includes the defined constraint for creating EDC assets.

This sequence diagram describes the process of how the policy with the defined constraint will be used for registering EDC data assets:

policy assets
Scenario 5: Updating notification offers when creating / deleting / updating policies

The Trace-X instance uses policies for creating the EDC catalog offers of notifications. These offers will be created on the following actions:

  • on Trace-X application startup

  • creating a policy for the own BPN

  • updating a policy for the own BPN

  • deleting a policy for the own BPN

This sequence diagram describes the process of how the catalog offers are updated after policy update / create / delete:

policy crud notification contract

Scheduler

An overview of the scheduler tasks configured in the system.

Scheduler name Execution interval Description

PublishAssetsJob

Every hour at 30min

Publishes assets in IN_SYNCHRONIZATION state to core services. The process combines as-built and as-planned assets and initiates their publication for synchronization in the traceability system.

AssetsRefreshJob

Every 2 hours

Invokes the synchronization of asset shell descriptors with the decentralized registry. It ensures the latest asset information is fetched and updated in the system from external sources.

Deployment view

Cross-cutting concepts

Entity-relationship model

Please be informed that the 'as-planned' version currently lacks the database relations.

Diagram

Domain concepts

API model

For detailed information about the API model, please refer to the API specification.

Domain models

Assets
level 1
Quality notifications
level 2

Safety and security concepts

Authentication / authorization

Trace-X API

The Trace-X API is secured using OAuth2.0 / Open ID Connect. Every request to the Trace-X API requires a valid bearer token. The JWT token should also contain two claims:

  • 'bpn' which is equal to the configuration value from API_ALLOWED_BPN property

  • 'resource_access' with the specific key for C-X environments. The list of values will be converted to roles by Trace-X. Currently, Trace-X API handles three roles: 'User' and 'Supervisor' and 'Admin'.

The roles and their functions are documented in the rights and role matrix in the system overview of the administration guide.

Trace-X as EDC client

The Trace-X accesses the Catena-X network via the EDC consumer connector. This component requires authentication via a Verifiable Credential (VC), which is provided to the EDC via the managed identity wallet.

The VC identifies and authenticates the EDC and is used to acquire access permissions for the data transferred via EDC.

Trusted Port for Internal APIs

A second port, called the trusted port, has been introduced which can only be accessed by internal services within the Kubernetes cluster. This measure is implemented to handle APIs that are difficult to secure and involve several systems and processes. The trusted port ensures that only internal, trusted components can access these sensitive APIs, enhancing overall security.

  • Quality notification callback APIs (receive, update) - called by EDC data plane

  • Endpoint Data Reference callback API - called by EDC control plane

Credentials

Credentials must never be stored in GitHub!

Architecture and design patterns

Module / package structure

  • Main domain name

    • Application

      • Optional: subdomain name (in case of inheritance) → following same structure as main domain

      • Mapper: holds the mapper of transforming domain models to response models

      • Service: holds the interface for implementation in the domain package

      • REST: holds the controller for providing the API for the domain

    • Domain

      • Optional: subdomain name (in case of inheritance)

      • Model: holds the domain model

      • Service: implementation of the interface provided in the application package

      • Repository: holds the interface for accessing the infrastructure package

    • Infrastructure

      • Optional: subdomain name (in case of inheritance)

      • Model: holds the technical entities

      • Repository: holds the data access layer

        • E.g. JPARepository / Impl

    • All models (request / response) used in the API should be saved in the tx-model project to be reusable for cucumber testing.

"Under-the-hood" concepts

Exception and error handling

There are two types of potential errors in Trace-X:

Technical errors

Technical errors occur when there is a problem with the application itself, its configuration or directly connected infrastructure, e.g. the Postgres database. Usually, the application cannot solve these problems by itself and requires some external support (manual work or automated recovery mechanisms, e.g. Kubernetes liveness probes).

These errors are printed mainly to the application log and are relevant for the health-checks.

Functional errors

Functional errors occur when there is a problem with the data that is being processed or external systems are unavailable and data cannot be sent / fetched as required for the process. While the system might not be able to provide the required function at that moment, it may work with a different dataset or as soon as the external systems recover.

Rules for exception handling
Throw or log, don’t do both

When catching an exception, either log the exception and handle the problem or rethrow it, so it can be handled at a higher level of the code. By doing both, an exception might be written to the log multiple times, which can be confusing.

Write own base exceptions for (internal) interfaces

By defining a common (checked) base exception for an interface, the caller is forced to handle potential errors, but can keep the logic simple. On the other hand, you still have the possibility to derive various, meaningful exceptions for different error cases, which can then be thrown via the API.

Of course, when using only RuntimeExceptions, this is not necessary - but those can be overlooked quite easily, so be careful there.

Central fallback exception handler

There will always be some exception that cannot be handled inside the code correctly - or it may just have been unforeseen. A central fallback exception handler is required so all problems are visible in the log and the API always returns meaningful responses. In some cases, this is as simple as an HTTP 500.

Don’t expose too much exception details over API

It’s good to inform the user why their request did not work, but only if they can do something about it (HTTP 4xx). So in case of application problems, you should not expose details of the problem to the caller. This way we avoid opening potential attack vectors.

Development concepts

Build, test, deploy

Trace-X is built using Maven and utilizes all the standard concepts of it. Test execution is part of the build process and a minimum test coverage of 80% is enforced.

The project setup contains a multi-module Maven build. Commonly used classes (like the Trace-X data model) should be extracted into a separate submodule and reused across the project. However, this is not a "one-size-fits-all" solution. New submodules should be created with care and require a review by the team.

The Maven build alone only leads up to the JAR artifact of Trace-X. To create Docker images, the Docker build feature is used. This copies all resources into a build image, builds the software and creates a final Docker image at the end that can then be deployed.

Although the Docker image can be deployed in various ways, the standard solution is to use the provided Helm charts, which describe the required components as well.

Code generation

There are two methods of code generation in Trace-X:

Lombok

The Lombok library is heavily used to generate boilerplate code (like constructors, getters, setters, builders…​). This way, code can be written faster and this boilerplate code is excluded from test coverage, which keeps the test base lean.

Swagger / OpenAPI

The API uses OpenAPI annotations to describe the endpoints with all necessary information. The annotations are then used to automatically generate the OpenAPI specification file, which can be viewed in the Swagger UI that is deployed with the application.

The generated OpenAPI specification file is automatically compared to a fixed, stored version of it to avoid unwanted changes of the API.

Migration

Data migration is handled by Flyway.

Configurability

Trace-X utilizes the configuration mechanism provided by Spring Boot. Configuration properties can be defined in the file src/main/resources/application.yml

Other profiles should be avoided. Instead, the configuration can be overwritten using Spring’s external configuration mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html). The operator must have total control over the configuration of Trace-X.

Java style guide

We generally follow the Google Java style guide.

API guide

We generally follow the OpenAPI specification.

Documentation style guide

We generally follow the Google developer documentation style guide.

Unit and functional testing

General unit testing

  • Code coverage >= 80%

  • Writing methods which provide a response to be better testable (avoid void if feasible).

  • Naming of unit tests are as follows:

unit test naming

  • Use the given / when / then pattern for unit test structuring. E.g:

given when then pattern
Integration testing

Each public API should have at least two integration tests (positive / negative). For integration testing, the file tx-backend/src/main/resources/application-integration.yml is used. Additionally, you need to have a local Docker environment running. For this, we recommend Rancher Desktop.

Clean code

We follow the rules and behaviour of: https://clean-code-developer.com/.

Secure coding standards

As there is no other guideline of C-X, we fix any vulnerabilities, exposures, flaws detected by one of our SAST, DAST, pen testing tools which are higher than "Very Low".

vulnerability level

Trace-X technical class responsibilities

Controller

  • Has only one dependency to a facade or a service or a validator annotation

  • Has no own logic

  • Includes the Swagger documentation annotations

  • Has an integration test class

  • Uses a static mapper to transform a domain model into the response model

  • Returns a ResponseEntity<T>

Response object

  • Should be a public version of the domain object

  • Is a result of the transformation which will be done in the facade

  • Is not necessary if the domain object can be fully public

  • Is not allowed to be implemented in a repository or a DAO

Facade

  • Should have multiple service classes injected

  • Can be implemented in a controller

ServiceImpl

  • Responsible for retrieving data from storage

  • Performs business logic

  • Can be a http client

  • Returns a jpaEntity → domain object

  • Should only be implemented in a controller through an interface

Repository

  • Represents an interface to the underlying repository implementation which then uses the spring repository

Domain object

  • Mapped from an entity or from received external data

  • Will be used as a working model until it will finally be transformed to a response object or another domain which will be persisted later on

Config object

  • Should have the suffix .config at the end of the class

  • Includes beans which are automatically created by app startup

Constructing objects

  • Using builder pattern

    • Currently, we are using the constructor to create objects in our application. Main reason is to provide immutable objects.

    • As the handling with big loaded constructors is not easy and error-prone, it’s recommended to use the builder pattern to have a clear understanding about what we are creating at the point of implementation.

  • Using lombok for annotation processing

Operational concepts

Administration

Configuration

Trace-X can be configured using two mechanisms:

application.yml

If you build Trace-X yourself, you can modify the application.yml config that is shipped with Trace-X. This file contains all possible config entries for the application. Once the Docker image has been built, these values can only be overwritten using the Spring external config mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html), e.g. by mounting a config file in the right path or using environment variables.

Helm chart

The most relevant config properties are exposed as environment variables and must be set in the Helm chart for the application to be able to run. Check the Trace-X Helm chart in GitHub for all available variables.

Scaling

If the number of consumers rises, Trace-X can be scaled up by using more resources for the deployment pod. Those resources can be used to utilize more parallel threads to handle job execution.

Clustering

Trace-X can run in clustered mode, as each running job is only present in one pod at a time. Note: as soon as a resume feature is implemented, this needs to be addressed here.

Logging

Logs are being written directly to stdout and are picked up by the cluster management.

Monitoring

Currently, there is on monitoring supported in Trace-X.

User experience

User interface

Table design

Trace-X uses the following table design to build consistent and user-friendly tables:

table design
Component Description Example

Actions

  • Black icons

  • When an action cannot be executed for any reason, the icon turns grey

  • A tooltip is shown when hovering over an executable action to describe it

  • A tooltip is shown when hovering over a disabled action to describe the reason why it can’t be executed

table actions

Action menus

  • Opens when clicking on a three-dot menu

  • Disappears, when clicking anywhere outside the menu

  • List of action icons with text labels

  • The three-dot menu is sticky when used inside the table for single-item actions

table action menus

Multi-select box

  • Clicking on it when no items are selected, selects all items on the current page

  • Clicking on it when some items are selected (but not all), selects all items on the current page

  • Clicking on it when all items are selected, deselects all items on the current page

  • Clicking on the small arrow opens a menu for clearing the page selection or the entire selection

  • The menu disappears, when clicking anywhere outside the menu

  • Part of the column header row → Sticky on top next to column headers

table multi select box

Selection box

  • Clicking on it toggles item selection

Selection count

  • Shows selection count of the current page

Column header

  • Shows the column title

  • Hovering over it shows a tooltip that describes sorting behaviour

  • Clicking on it toggles sorting

  • Sticky on top

table sorting tooltip Ascending sorting: table sorting ascending Descending sorting: table sorting descending

Filter

  • Can search for any string

  • Results are shown directly without having to press enter

  • Results are shown as a sorted list (ascending)

  • Selected results are shown on top of unselected ones

  • The checkbox inside the search field selects or deselects every result

  • The cross inside the search field resets the search and the filter

  • When the filter is active, 'All' changes to the filtered value (+ the number of other filters)

  • For date values, the search is replaced with a date picker

  • Sticky on top below column headers

table filter Date filter: table filter date

Quick filter

  • Used to quickly filter for specific values

  • Independent of regular filters

  • Work exclusively - only one filter can be selected at a time

  • Click on the currently active quick filter to deactivate it

Table column settings

  • Opens up as an overlay

  • Clicking on Save, the cross or anywhere outside the overlay will close the overlay (only saving changes when clicking Save)

  • Selecting/deselecting columns makes them visible/invisible in the table

  • The order of the columns can be changed by selecting the column title and using the arrow buttons

  • Using the circle arrow icon resets the column visibility and column order

table column settings

Full-width toggle

  • Used to switch between full-width mode or variable-width mode

Scrollbars

  • Only visible/active when data exceeds the visible space

  • Sticky elements stay visible regardless of scroll position

Page size selector

  • Shows the currently selected page size

  • When clicking on it, a dropdown opens that shows available page size options

  • Clicking any option will select that option and close the dropdown

  • Clicking anywhere outside the dropdown closes the dropdown without applying any changes

  • Three options are always available

table page size selector

Page information

  • Shows information about the amount of items on the current page and the total amount of items

Page controls

  • Used to switch between pages

  • Controls are: First page, previous page, next page, last page

  • Hovering over the controls shows a tooltip that labels each control

table page controls

In addition, following tables are used within Trace-X:

When the data is not as complex and/or extensive and single-item actions are not needed:

table small

When data must only be shown and no actions are needed:

table data only

Quality requirements

This section includes concrete quality scenarios to better capture the key quality objectives but also other required quality attributes.

Quality tree

The tree structure provides an overview for a sometimes large number of quality requirements.

business context 2

Quality scenarios

The initial letters of the scenario identifiers (IDs) in the following table each stand for the higher-level quality characteristic. For example M for maintainability. These identifiers are also used in the quality tree. The scenarios cannot always be clearly assigned to a characteristic. Therefore, they sometimes appear more than once in the quality tree.

ID Scenario

M01

Developers with basic knowledge of the traceability use case look for an introduction to the traceability architecture. They get the idea of essential design very fast.

M02

Senior developers look for a reference implementation of the traceability use case functionalities. They get it within the source code.

M03

Developers want to implement new features. They are able to add it to the source code easily.

M04

Developers want to implement a new frontend or change some components. The efforts can be reduced by using the standardized API endpoints to do so.

I01

Users want to switch from a FOSS application to a COTS application or the other way round. This is possible since the application is interoperable with other applications within the CX network.

F01

The application uses the Catena-X standards to ensure the correct interoperability and exchange with other participants.

F02

An OEM or tier n supplier needs more information regarding specific parts. He can mark the parts in question and send a top-down notification (quality investigation) to the next entity / the partner.

F03

A company wants to have more transparency and a visualized status of the supply / value chain. By using the application they are enabled to work with the structures and enable new features / functionalities.

F04

Notifications are sent using the EDC to ensure interoperability with the CX network.

E01

Notifications between traceability apps need to be sent and received within a specified timeframe to minimize the negative impact of e.g. recalled serialized products / batches on the value chain.

Glossary

Term Description

Aspect

Collection of various aspects from the digital twin. An aspect can, for example, bundle all information about a specific part.

AAS

Asset Administration Shell (Industry 4.0) is the implementation of the digital twin for Industry 4.0 and enables interoperability between different companies.

BoM

Bill of Material. BoM is a list of parts and materials that a product contains. Without them, manufacturing would not be possible.

BoM AsBuilt

Bill of material lifecycle of the built entity

BoM AsPlanned

Bill of material lifecycle of the planned entity

BPN

Business Partner Number. A BPN is used to identify a partner in the Catena-X network.

CX

Abbreviation for Catena-X

Data Sovereignty

Ability to keep control over own data, that is shared with other participants

EDC

Eclipse Dataspace Connector. The connector version used in Catena-X

FOSS

Free and Open Source Software

Interoperability

Communication and interaction with other components or Catena-X partners / players

IRS

Item Relationship Service. Component to provide data chains. IRS architecture documentation (arc42)

SME

Small / Medium Enterprise

Trace-X

Proper name of open-source software application of Catena-X use case traceability

UI

User Interface