Version: 24.03

Data Provider

Traceability kit banner

The following page offers specific developer resources, including payloads and API endpoints for data providers. It is important to read the business and architecture view first to understand everything.

Aspect Models

Aspect models are mostly easy to create by transforming a company's internal data into the target aspect model. Transformations are mostly straightforward in these cases. If necessary, special steps in creating aspect models are mentioned in the corresponding sections.

In the following section, all aspect models that are part of Industry Core are documented.

Digital Twin Type	Aspect Model	Mandatory Supported Version	Optionally Supported Versions	KIT
PartType	PartAsPlanned	1.0.1	2.0.0	Industry Core
	SingleLevelBomAsPlanned	1.1.0	2.0.0	Industry Core
	PartSiteInformationAsPlanned	1.0.0		Industry Core
	SingleLevelUsageAsPlanned	1.1.0		Traceability
PartInstance	SerialPart	1.0.1	2.0.0	Industry Core
	Batch	2.0.0	2.0.1	Industry Core
	JustInSequencePart	1.0.0	2.0.0	Industry Core
	SingleLevelBomAsBuilt	1.0.0	2.0.0	Industry Core
	PartSiteInformationAsBuilt (shared aspect)	1.0.0		Industry Core
	SingleLevelUsageAsBuilt	2.0.0		Traceability
	TractionBatteryCode	1.0.0		Traceability

SingelLevelUsageAsPlanned

The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list.

Aspect model in GitHub:

Version 1.1.0: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0

Example: Submodel `SingleLevelUsageAsPlanned` for a Catalog Part

{
  "parentParts": [
    {
      "parentCatenaXId": "urn:uuid:c8B01D5A-ce0B-6Dd4-5bA0-A3e3fcE9cA93",
      "quantity": {
        "quantityNumber": 2.5,
        "measurementUnit": "unit:litre"
      },
      "createdOn": "2022-02-03T14:48:54.709Z",
      "lastModifiedOn": "2022-02-03T14:48:54.709Z"
    }
  ],
  "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d"
}

TractionBatteryCode

The aspect provides the information of the Traction battery code of a battery cell, a battery module or a battery pack according to the chinese standard GB/T 34014-2017. Furthermore, it provides the traction battery codes for the assembled sub parts of the component, e.g. Traction battery code of a battery module plus all the traction battery codes of the assembled battery cells of this battery module.

Aspect model in GitHub:

Version 1.0.0: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0

Example: Submodel `TractionBatteryCode` for a Battery Cell

{
  "productType": "cell",
  "tractionBatteryCode": "X12CCPM27KLPCLE662382320"
}

Example: Submodel `TractionBatteryCode` for a Battery Module

{
  "productType": "module",
  "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857",
  "subcomponents": [
    {
      "productType": "cell",
      "tractionBatteryCode": "X12CCPM27KLPCLE662382320"
    },
    {
      "productType": "cell",
      "tractionBatteryCode": "X12CCPM27KLPCLE662382321"
    }
  ]
}

Example: Submodel `TractionBatteryCode` for a Battery Pack

{
  "productType": "pack",
  "tractionBatteryCode": "4A6PCPM27KLPCLE742946319",
  "subcomponents": [
    {
      "productType": "module",
      "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857",
      "subcomponents": [
        {
          "productType": "cell",
          "tractionBatteryCode": "X12CCPM27KLPCLE662382320"
        },
        {
          "productType": "cell",
          "tractionBatteryCode": "X12CCPM27KLPCLE662382321"
        }
      ]
    },
    {
      "productType": "module",
      "tractionBatteryCode": "B54MCPM27KLPCLE6A7519858",
      "subcomponents": [
        {
          "productType": "cell",
          "tractionBatteryCode": "X12CCPM27KLPCLE662382322"
        },
        {
          "productType": "cell",
          "tractionBatteryCode": "X12CCPM27KLPCLE662382323"
        }
      ]
    }
  ]
}

SingleLevelUsageAsBuilt

Aspect model in GitHub:

Version 2.0.0: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_built/2.0.0

Example: Submodel `SingleLevelUsageAsBuilt` for a Instance Part

{
  "catenaXId" : "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d",
  "customers" : [ {
    "parentItems" : [ {
      "catenaXId" : "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d",
      "quantity" : {
        "quantityNumber" : 2.5,
        "measurementUnit" : "unit:litre"
      },
      "createdOn" : "2022-02-03T14:48:54.709Z",
      "lastModifiedOn" : "2022-02-03T14:48:54.709Z"
    } ],
    "businessPartner" : "BPNL50096894aNXY",
    "createdOn" : "2022-02-03T14:48:54.709Z",
    "lastModifiedOn" : "2022-02-03T14:48:54.709Z"
  } ]
}

Policies

Access Policies

Access policies like the BPN access policy are described in the policy section of the Industry Core KIT.

Usage Policies / Contract Policies

It is recommended to restrict the data usage for all traceability aspects. An example of one usage policy containing three different constraints is shown and described in the following:

{
  "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
  },
  "@type": "PolicyDefinitionRequestDto",
  "@id": "<POLICY-ID>", // Important for the contract definition
  "policy": {
    "@type": "Policy",
    "odrl:permission": [
      {
        "odrl:action": "USE",
        "odrl:constraint": {
          "@type": "LogicalConstraint",
          "odrl:and": [ // All of the following three constraints have to be fullfilled (and, not or)
            // First constraint to verify the the Catena-X membership
            {
              "@type": "Constraint",
              "odrl:leftOperand": "Membership",
              "odrl:operator": {
                "@id": "odrl:eq"
              },
              "odrl:rightOperand": "active"
            },
            // Second constraint to verify if the framework agreement for the traceability use case is accepted
            {
              "@type": "Constraint",
              "odrl:leftOperand": "FrameworkAgreement.traceability",
              "odrl:operator": {
                "@id": "odrl:eq"
              },
              "odrl:rightOperand": "active"
            },
            // Third constraint to define the specific purpose, further detailed in the framework agreement
            {
              "@type": "Constraint",
              "odrl:leftOperand": "PURPOSE",
              "odrl:operator": {
                "@id": "odrl:eq"
              },
              "odrl:rightOperand": "<POSSIBLE-PURPOSE-STRING>" // See list in the framework agreement
            }
          ]
        }
      }
    ]
  }
}

✋ Standardization Keep in mind that the odrl:leftOperand and the odrl:rightOperand will be standardized. Therefore, check the latest JSON payload after every release if it is still up-to-date. Otherwise, data sharing might not be possible if the policies are wrong.

Membership Policy

To verify the participants Catena-X membership, the Membership verifiable credential can be used. In case of a policy, the data can only be used from verified Catena-X members. The payload is shown in the first constraint-part of the example above and described in detail in the EDC part of the SSI documentation.

{
  "@type": "Constraint",
  "odrl:leftOperand": "Membership",
  "odrl:operator": {
    "@id": "odrl:eq"
  },
  "odrl:rightOperand": "active"
}

Framework Agreement Policy

To verify if a participant accepted the framework agreement of a specific use case created by the Catena-X association, the FrameworkAgreement.traceability verifiable credential can be used for the traceability framework agreement. Further details and the framework agreement itself can be downloaded from the Governance Framework for Data Space Operations. In case of a policy, the data can only be used from accepted and verified traceability framework agreement members. This is shown in the second constraint-part of the example above and described in detail in the EDC part of the SSI documentation.

{
  "@type": "Constraint",
  "odrl:leftOperand": "FrameworkAgreement.traceability",
  "odrl:operator": {
    "@id": "odrl:eq"
  },
  "odrl:rightOperand": "active"
}

Purpose-based Policy

To further restrict the data usage, a purpose-based policy can be used. If, for example, the purpose mentions a quality investigation, this means that the data usage is only allowed for handling and working on the quality investigation. All possible purposes and their meanings are defined in the traceability framework agreement. This allows to create a uniform understanding and a standardized set of payloads in the network by connecting technical strings to legal agreements.

It is highly recommended to only use this purpose-based policy together with the Framework Agreement Policy. Only with both together it can be ensured that the payload of the purpose policy is agreed by the other part and is based on the same set.

Details about the endpoint and payload can be found in the Transfer Data sample in the tractus-x EDC repository.

{
  "@type": "Constraint",
  "odrl:leftOperand": "PURPOSE",
  "odrl:operator": {
    "@id": "odrl:eq"
  },
  "odrl:rightOperand": "<POSSIBLE-PURPOSE-STRING>"
}

The <POSSIBLE-PURPOSE-STRING> have to be replaced with one purpose string defined in the traceability framework agreement.

Individual Agreements and Contracts

There might be some individual agreements and contracts between two companies. It is possible to reference such a bilateral contract with the purpose-based policy. In this case, the odrl:rightOperand includes the unique reference to the contract. It is planned to standardize the format in future upcoming releases.

Contract Definitions

In a last step, these policies need to be connected to the data by a contract definition (see Transfer Data sample in the tractus-x EDC repository for further details). When using an Access Policy, their id needs to be included as a value of the accessPolicyId key in the contract definition. When using an above-mentioned Usage Policy, their id needs to be included as a value of the contractPolicyId key in the contract definition.

NOTICE

This work is licensed under the CC-BY-4.0.

SPDX-License-Identifier: CC-BY-4.0
SPDX-FileCopyrightText: 2023 BASF SE
SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML)
SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG
SPDX-FileCopyrightText: 2023 Mercedes Benz AG
SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH
SPDX-FileCopyrightText: 2023 SAP SE
SPDX-FileCopyrightText: 2023 Siemens AG
SPDX-FileCopyrightText: 2023 T-Systems International GmbH
SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG
SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation
Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version)

Aspect Models​

SingelLevelUsageAsPlanned​

Example: Submodel SingleLevelUsageAsPlanned for a Catalog Part​

TractionBatteryCode​

Example: Submodel TractionBatteryCode for a Battery Cell​

Example: Submodel TractionBatteryCode for a Battery Module​

Example: Submodel TractionBatteryCode for a Battery Pack​

SingleLevelUsageAsBuilt​

Example: Submodel SingleLevelUsageAsBuilt for a Instance Part​

Policies​

Access Policies​

Usage Policies / Contract Policies​

Membership Policy​

Framework Agreement Policy​

Purpose-based Policy​

Individual Agreements and Contracts​

Contract Definitions​

NOTICE​

Aspect Models

SingelLevelUsageAsPlanned

Example: Submodel `SingleLevelUsageAsPlanned` for a Catalog Part

TractionBatteryCode

Example: Submodel `TractionBatteryCode` for a Battery Cell

Example: Submodel `TractionBatteryCode` for a Battery Module

Example: Submodel `TractionBatteryCode` for a Battery Pack

SingleLevelUsageAsBuilt

Example: Submodel `SingleLevelUsageAsBuilt` for a Instance Part

Policies

Access Policies

Usage Policies / Contract Policies

Membership Policy

Framework Agreement Policy

Purpose-based Policy

Individual Agreements and Contracts

Contract Definitions

NOTICE