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.
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.
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:
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:
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:
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.
Module 2
The frontend is able to select assets and publish / synchronize them with the shared services DTR / EDC / submodel API.
Module 3
The backend is able to persist the data in the DTR / EDC and enables the IRS to resolve assets.
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.
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
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).
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).
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
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
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
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
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:
The catalog offer contains the policy definition of the default policy:
In this state both companies can send notifications to each other.
Step 2
In this example Trace-X B creates a new policy:
Once created, the catalog offer will be updated using this policy:
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:
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 5
Now Trace-X A can create a new policy using the same constraints as Trace-X B’s policy:
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:
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:
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.
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:
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:
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:
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. |