Skip to main content
Release: 24.03 (deprecated)

CX-0125 Traceability Use Case v1.0.0

ABSTRACT

This standard is used to define the ground rules to participate in the Traceability Use Case.

The use case is based on the industry core and uses the digital twins and aspect models of the industry core. Furthermore it includes use case-specific aspect models (for e.g. TractionBatteryCode) that go beyond the industry core and are used to make various entities in the network, such as parts, traceable.

In addition, this document contains necessary standards for applications to send standardized notifications to exchange Quality Alerts and Quality Investigation in Catena-X. Quality Investigation refer to sending standardised notifications to suppliers (top-down) while Quality Alerts refer to sending notifications to customers (bottom-up). Those notifications will enable the industry to exchange and act upon quality issues in a more standardised, integrated, accelerated and precise manner. This document describes the minimal requirements of the notification process a traceability application or application stack needs to fulfill for being interoperable within the Catena-X platform as well as the specific API endpoints and their integration into IDSA conform data assets.

FOR WHOM IS THE STANDARD DESIGNED

This standard is aimed both at participants (users) in the automotive value chain and at stakeholders who provide users to participate in the traceability use case.

The following features are provided:

  • Traceability of products (e.g. vehicles), parts and material (physical assets)
  • Notification of quality issues within the value chain

The following roles are focused by this document:

  • Consulting Provider (e.g. Certified Onboarding Partner)
  • Business Application Provider
  • Enablement Service Provider
  • Data Consumer (for Notifications)
  • Data Provider (for Notifications)
  • Conformity Assessment Bodies (CAB)

COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD

This document summarizes all relevant standards for the Traceability Use Case. This standard builds upon the Traceability-Triangle and different aspect models but in its present form has no previous version.

The following standards shall be deprecated since their contents are incorporated into this new standard document:

  • CX-0062-TraceabilityNotificationsTriangle-v1.0.0
  • CX-0093-AspectModelTractionBatteryCode-v1.0.0
  • CX-0022-Notification_Process-v1.1.1
  • CX-0023-NotificationAPI-v1.2.2

1 INTRODUCTION

This document summarizes all standards to be supported by a network participants IT infrastructure to participate for the Traceability Use Case. This involves protocols, semantic models and platform capabilities to be used.

1.1 AUDIENCE & SCOPE

This section is non-normative

This document is targeting subsets of the following roles:

  • Data Provider (only for notifications) / Consumer
  • Business Application Provider
  • Enablement Service Provider

Furthermore, this standard applies to Traceability Applications or Application stacks and participants that

  • want to provide (only for notifications) and/or consume data
  • want to exchange quality notifications and quality investigations data leveraging Traceability solutions

Note: Fulfilling a use-case standard by a data provider / consumer can be done in two ways: A) Purchase a certified app for the use-case. In this case the data provider / consumer does not need to prove conformity again. B) Data Provisioning / Consumption without a certified app for the use-case. In this case the data provider / consumer needs to prove conformity with all single standards listed in this document.

1.2 CONTEXT AND ARCHITECTURE FIT

This section is non-normative

Traceability of parts and materials is crucial in the automotive industry to enable e.g. quality management and circular economy. So, the aim of the Use Case Traceability is to trace physical parts and materials across the entire value creation chain to enable data driven use cases over all n-tier levels without compromising data sovereignty.

In order to create this transparency on physical assets, relevant data must be made available by all participants of the automotive value chain. This process is described in the standard CX - 0127 INDUSTRY CORE: PART INSTANCE 1.0.0. This standard enables data and app providers to deliver solutions for building data chains for serialized parts or batches. This is achieved via the standardized creation of digital twins of vehicles, parts and materials as well as the logical linking to their sub-components (Bill of Material, BoM). The default visibility of digital twins and their respective semantic models follows the one-up/one-down principle.

By tracking and tracing back the sourcing of serialized parts or batches, manufactures can quickly identify the source of any quality issue and take corrective actions to address them. Comprehensive traceability across the value creation network enables the automotive and further industries to quickly respond to any quality issues in their supply chain. Standardized Quality Alerts and Quality Investigation based on Part Instance digital twins (CX-0127 INDUSTRY CORE - PART INSTANCE) may be used for this purpose within the Catena-X network.

1.3 CONFORMANCE AND PROOF OF CONFORMITY

This section is non-normative

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

All participants* and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Please refer to: https://catena-x.net/en/catena-x-introduce-implement/certification for the process of conformity assessment and certification.

Since this document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document.

The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components.

The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data.

In terms of conformity the openAPI specification of the application or endpoints being exposed via the EDC or any similar IDS conformant connector MUST be checked against the standardized openAPI specification.

Examples of data assets and contract offer structure in the EDC or any other IDS protocol compliant connector MUST correspond to the described structure.

*Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. This will include the roles, certification and further assessment procedures as well as the rollout phases.

1.4 EXAMPLES

Corresponding examples are provided as sub-chapters in the respective sections.

1.5 TERMINOLOGY

This section is non-normative

Application Programming Interface (API) An API is a way for two or more computer programs to communicate with each other.

Aspect Model A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an aspect.

Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model.

Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing).

[Source: Catena-X, CX-0002, note 3 removed]

Asset An Asset describes on Data Provider side the data set which will be shared or can be consumed by a Data Consumer.

Asset Administration Shell (AAS) The AAS is a digital representation of an asset. It is a form of a digital twin.

Bill of Material (BoM) A bill of material resembles the structure of an end product. It is a list of all raw materials, sub-assemblies and sub-components that are needed to manufacture the end procuct. At Catena-X Traceability we consider more than one single BoM. The BoM changes during the lifecyle and therefore, we are talking about different BoMs in different lifecycles.

Business Partner Number (BPN) A BPN is the unique identifier of a partner within Catena-x.

Eclipse Dataspace Connector (EDC) The EDC is a reference implementation for an IDS compliant connector currently acting as a de-facto standard and/or reference Implementation within Catena-X.

International Data Space Association (IDSA) The IDSA is on a mission to create the future of the global, digital economy with International Data Spaces (IDS), a secure, sovereign system of data sharing in which all participants can realize the full value of their data.

International Data Space (IDS) The International Data Space enables new "smart services" and innovative business processes to work across companies and industries while ensuring that the self-determined control of data use (data sovereignty) remains in the hands of data providers.

IDSA Protocol The IDSA Protocol being used for data exchange in an International Dataspace. This includes contract negotiation.

Part Instance A part instance is a physically produced instance (e.g. serialized part, batch, just-in-sequence-part) of a part type.

Serialized part: Instance of a part, where the particular instance can be uniquely identified by means of a serial number, a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number).

Subcomponent A Subcomponent is a separate product that can be assembled into a customer product.

Vehicle Anonymised Number (VAN) A number mapped 1:1 to VIN, but pseudonomised.

Vehicle Identification Number (VIN) The VIN number is a 17-character code assigned by the manufacturer to every vehicle, providing specific information about its make, model, year of manufacture, and other key features. It is a unique identifier that allows the vehicle to be easily tracked and identified throughout its lifespan. Additional terminology used in this standard can be looked up in the glossary on the association homepage.

2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES

This section is normative

2.1 "NOTIFICATIONS"

This chapter describes and collects necessary standards for applications that enable the exchange of Quality Alert and Quality Investigation in Catena-X. Quality refer to sending standardised notifications to suppliers (top-down) while Quality Alerts refer to sending notifications to customers (bottom-up). Those notifications will enable the industry to exchange and act upon quality issues in a more standardised, integrated, accelerated and precise manner.

2.1.1 LIST OF STANDALONE STANDARDS

This section is normative

To participate in Notifications, the following single standards MUST be fulfilled by all participants for which the standard is relevant:

  • CX-0018 ECLPISE DATA SPACE CONNECTOR (EDC)

The described Notification Process MUST be supported and described Notification API MUST be provisioned in order to receive Quality Alerts or Quality Investigation. The IDS protocol as described in CX-0018 MUST be followed in the data exchange. The Eclipse Dataspace Connector as a reference implementation is RECOMMENDED to be used as an IDS compliant connector. As basis for the Quality Alerts and Quality Investigation MUST be used either the standard for Part Instance described in CX - 0127 INDUSTRY CORE: PART INSTANCE 1.0.0 OR the combination of follwings standards

  • CX-0019 ASPECT MODEL SERIAL PART 2.0.0
  • CX-0021 ASPECT MODEL BATCH 2.0.0
  • CX-0020 ASPECT MODEL SINGLE LEVEL BOM AS BUILT 2.0.0

2.1.2 DATA REQUIRED

A digital twin MAY be created for serialized part or batch of materials produced by the manufacturer. The digital twin MUST be provisioned via an Asset Administration Shell as per CX-0002 and registered in a decentral Digital Twin Registry of the data provider (or the decentral Digital Twin Registry host of the manufacturer) as described in CX-0002.

The aspect model "SerialPart" MUST be linked to the Asset Administration Shell of a serialized part. The aspect model "Batch" MUST be linked to the Asset Administration Shell of a Batch.

The aspect model "SingleLevelBomAsBuilt" MUST be linked to the Asset Administration Shell of each part and each batch holding the information on relationship of serialized items and batches. Information on the Bill of Material of those parts and batches MUST NOT be provided in any other way than with the aspect model "SingleLevelBomAsBuilt".

The submodel data MUST be transferred using the IDS Protocol as described in CX-0018. The Eclipse Dataspace Connector as a reference implementation is RECOMMENDED to be used as an IDS compliant connector.

2.1.3 ADDITIONAL REQUIREMENTS

As the IDS protocol is being used, data MUST NOT be transferred before a corresponding contract negotiation has been successfully passed by the participants of the data exchange and a valid contract is present as described in CX-0018. The required data offers for Quality Alerts and Quality Investigations MUST be created and linked to the described endpoints of the Notification API. The process and especially status schema depicted in chapter Notification Process MUST be supported.

3 ASPECT MODELS

This section is normative

An overview of the relevant aspect models of this standard.

  • SerialPart
  • Batch
  • JustInSequencePart
  • SingleLevelBomAsBuilt
Every certified business application relying on the Industry Core: Part Instance data **MUST** be able to consume data conformant to the semantic models specified in this document.
Data consumers and data provider **MUST** comply with the license of the semantic models.
The submodel data **MUST** be requested and exchanged via Eclipse Dataspace Connector (EDC) conformant to CX-0018 and CX-0002.
Data providers **MUST** provide data as part of a digital twin of the asset for serialized parts conformant to CX – 0002 DIGITAL TWINS IN CATENA-X .
The JSON Payloads of data providers **MUST** be conformant to the JSON Schemas as specified in this document.
The unique identifier of the semantic model specified in this document **MUST** be used by the data provider to define the semantics of the data being transferred.

3.1 ASPECT MODEL "SerialPart"

3.1.1 INTRODUCTION

The semantic model SerialPart describes a submodel for a digital twin of a serialised part providing essential information about this part. A serialized part is an instance of a part, where the particular instance can be uniquely identified by means of a serial number, a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number). More specific, the model links local identifiers like manufacturerPartId, customerPartId and other data like manufacturing information and part type information to the actual catenaXId from Catena-X, which is a UUIDv4. This allows decoupling of the network identifiers from the actual business process. By accessing this aspect you can link a physical part to its representation within Catena-X.

Note: The version 1.0.1 is the current version and mandatory. If existing, versions higher than that are optional, but shall be mandatory in new standard versions.

3.1.2 SPECIFICATIONS ARTIFACTS

The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification SMT.

The aspect model SerialPart v1.0.1 is written in BAMM 2.0.0, and SerialPart v2.0.0 in SAMM 2.0.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow.

Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003.

3.1.3 LICENSE

This Catena-X data model is an outcome of Catena-X use case group Traceability. This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons1.

The license information is available in github.

In case of doubt the license, copyright and authors information in github overwrites the information in this specification document.

3.1.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

SerialPart v1.0.1 (mandatory)

**urn:bamm:io.catenax.serial_part:1.0.1#SerialPart**

SerialPart v2.0.0 (optional)

**urn:bamm:io.catenax.serial_part:2.0.0#SerialPart**

3.1.5 FORMATS OF SEMANTIC MODEL

3.1.5.1 RDF TURTLE

The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. These can be viewed by following links:

SerialPart v1.0.1 (mandatory)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.serial_part/1.0.1/SerialPart.ttl

SerialPart v2.0.0 (optional)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.serial_part/2.0.0/SerialPart.ttl

The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation.

3.1.5.2 JSON SCHEMA

A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel".

3.1.5.3 AASX

An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to [SMT].

3.1.6 EXAMPLE DATA

Example JSON payload: Submodel "SerialPart" v1.0.1 for a vehicle

{
"localIdentifiers": [
{
"key": "manufacturerId",
"value": "BPNL7588787849VQ"
},
{
"key": "manufacturerPartId",
"value": "95657362-83"
},
{
"key": "partInstanceId",
"value": "OEM-A-F8LM95T92WJ9KNDD3HA5P"
},
{
"key": "van",
"value": "OEM-A-F8LM95T92WJ9KNDD3HA5P"
}
],
"manufacturingInformation": {
"date": "2022-02-04T14:48:54",
"country": "DEU"
},
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"partTypeInformation": {
"manufacturerPartID": "QX-39",
"classification": "product",
"nameAtManufacturer": "Vehicle Model A"
}
}

Example JSON payload: Submodel "SerialPart" v1.0.1 for a Serialized Part (Non-Vehicle)

{
"localIdentifiers": [
{
"key": "manufacturerId",
"value": "BPNL7588787849VQ"
},
{
"key": "manufacturerPartId",
"value": "95657362-83"
},
{
"key": "partInstanceId",
"value": "NO-574868639429552535768526"
}
],
"manufacturingInformation": {
"date": "2022-02-04T14:48:54",
"country": "DEU"
},
"catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04",
"partTypeInformation": {
"manufacturerPartID": "95657362-83",
"customerPartId": "798-515297795-A",
"classification": "component",
"nameAtManufacturer": "High Voltage Battery",
"nameAtCustomer": "High Voltage Battery"
}
}

Example JSON payload: Submodel "SerialPart" v2.0.0 for a vehicle

{
"localIdentifiers": [
{
"key": "manufacturerId",
"value": "BPNL7588787849VQ"
},
{
"key": "manufacturerPartId",
"value": "95657362-83"
},
{
"key": "partInstanceId",
"value": "OEM-A-F8LM95T92WJ9KNDD3HA5P"
},
{
"key": "van",
"value": "OEM-A-F8LM95T92WJ9KNDD3HA5P"
}
],
"manufacturingInformation": {
"date": "2022-02-04T14:48:54",
"country": "DEU"
},
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"sites": [
{
"catenaXsiteId": "BPNS1234567890ZZ",
"function": "production"
}
],
"partTypeInformation": {
"manufacturerPartID": "QX-39",
"classification": "product",
"nameAtManufacturer": "Vehicle Model A"
}
}

Example JSON payload: Submodel "SerialPart" v2.0.0 for a Serialized Part (Non-Vehicle)

{
"localIdentifiers": [
{
"key": "manufacturerId",
"value": "BPNL7588787849VQ"
},
{
"key": "manufacturerPartId",
"value": "95657362-83"
},
{
"key": "partInstanceId",
"value": "NO-574868639429552535768526"
}
],
"manufacturingInformation": {
"date": "2022-02-04T14:48:54",
"country": "DEU"
},
"catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04",
"sites": [
{
"catenaXsiteId": "BPNS1234567890ZZ",
"function": "production"
}
],
"partTypeInformation": {
"manufacturerPartID": "95657362-83",
"customerPartId": "798-515297795-A",
"classification": "component",
"nameAtManufacturer": "High Voltage Battery",
"nameAtCustomer": "High Voltage Battery"
}
}

3.2 ASPECT MODEL "Batch"

3.2.1 INTRODUCTION

A batch is a quantity of (semi-) finished products or (raw) material product that have been produced under the same circumstances (e.g., same production location), as specified groups or amounts, within a certain time frame. Every batch can differ in the number or amount of products. Different batches can have varied specifications, e.g., different colors, quality, etc. A batch is identified via a Batch ID.

This submodel template or aspect model is required to identify a batch of materials within Catena-X.

It links local identifiers like manufacturerPartId and batchId to the actual Catena-X ID.

This allows decoupling of the Catena-X identifiers from the actual business process.

By accessing this aspect you can link a physical batch of parts to its representation within in Catena-X.

Note: The version 2.0.0 is the current version and mandatory. If existing, versions higher than that are optional, but shall be mandatory in new standard versions.

3.2.2 SPECIFICATIONS ARTIFACTS

The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification SMT.

The aspect model Batch is written in SAMM 2.0.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow.

Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003.

3.2.3 LICENSE

   
This Catena-X data model is an outcome of Catena-X use case group
Traceability. This Catena-X data model is made available under the terms
of the Creative Commons Attribution 4.0 International (CC-BY-4.0)
license, which is available at Creative Commons[^2].

The license information is available in github.

In case of doubt the license, copyright and authors information in
github overwrites the information in this specification document.

3.2.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier Batch v2.0.0 (mandatory)

**urn:samm:io.catenax.batch:2.0.0#Batch**

Batch v2.0.1 (optional)

**urn:samm:io.catenax.batch:2.0.1#Batch**

3.2.5 FORMATS OF SEMANTIC MODEL

3.2.5.1 RDF TURTLE

The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. These can be viewed by following links:

Batch v2.0.0 (mandatory)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/2.0.0/Batch.ttl

Batch v2.0.1 (optional)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/2.0.1/Batch.ttl

The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation.

3.2.5.2 JSON SCHEMA

A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel".

3.2.5.3 AASX
An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested
artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)].

3.2.6 EXAMPLE DATA

Example JSON payload: Submodel "Batch" v2.0.0

{
"localIdentifiers":[
{
"value":"BID12345678",
"key":"batchId"
}
],
"manufacturingInformation":{
"date":"2022-02-04T14:48:54",
"country":"HUR"
},
"catenaXId":"580d3adf-1981-44a0-a214-13d6ceed9379",
"partTypeInformation":{
"manufacturerPartId":"123-0.740-3434-A",
"classification":"product",
"nameAtManufacturer":"Mirror left",
}

Example JSON payload: Submodel "Batch" v2.0.1

{
"localIdentifiers": [
{
"value": "BID12345678",
"key": "batchId"
}
],
"manufacturingInformation": {
"date": "2022-02-04T14:48:54",
"country": "HUR"
},
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"sites": [
{
"catenaXsiteId": "BPNS1234567890ZZ",
"function": "production"
}
],
"partTypeInformation": {
"manufacturerPartId": "123-0.740-3434-A",
"classification": "product",
"nameAtManufacturer": "PA66-GF30",
}
}

3.3 ASPECT MODEL "SingleLevelBomAsBuilt"

3.3.1 INTRODUCTION

The Industry Core: Part Instance aims on building product genealogy information throughout the supply chain. Therefore it is required to link a produced part with its predecessor items. SingleLevelBoMAsBuilt is the submodel to build such linkage between the digital twins. It contains the unique identifiers of the predecessor items of a produced or assembled part and therefore allows navigation through the supply chain by Catena-X identifiers.

More specific, the aspect provides information on the child items (one structural level down) from which the given object is assembled. In first priority, it creates the relationship of one part instance in the asBuilt lifecycle phase with its child items by referencing the part instance digital twin of such item. However, when no part instance digital twin of the child item exists to reference, it is in a second priority possible to reference the part type twin of the child item instead.

Because of gap of information in the production, it is sometimes not possible to identify the single correct digital twin to reference, but just a subset of potential twins. Then all potential alternative twins may be referenced. This will be marked by setting the property "hasAlternatives" true. If the exact digital twin is known, regardless of if it is a part type or part instance, just this one will be referenced and "hasAlternative" will be false.

Note: The version 2.0.0 is the current version and mandatory. If existing, versions higher than that are optional, but shall be mandatory in new standard versions.

3.3.2 SPECIFICATIONS ARTIFACTS

The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification SMT.

The aspect model Batch is written in SAMM 2.0.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow.

Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003.

3.3.3 LICENSE

This Catena-X data model is an outcome of Catena-X use case group Traceability. This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons1.

The license information is available in github.

In case of doubt the license, copyright and authors information in github overwrites the information in this specification document.

3.3.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

SingleLevelBomAsBuilt v2.0.0 (mandatory)

**urn:samm:io.catenax.single_level_bom_as_built:2.0.0#SingleLevelBomAsBuilt**

3.3.5 FORMATS OF SEMANTIC MODEL

3.3.5.1 RDF TURTLE

The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. These can be viewed by following links:

SingleLevelBomAsBuilt v2.0.0 (mandatory)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_built/2.0.0/SingleLevelBomAsBuilt.ttl

The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation.

3.3.5.2 JSON SCHEMA

A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel".

3.3.5.3 AASX

An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to [SMT].

3.3.6 EXAMPLE DATA

Example JSON payload: Submodel "SingleLevelBomAsBuilt" v2.0.0 for a SerialPart

{
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"childItems": [
{
"quantity": {
"quantityNumber": 1.0,
"measurementUnit": "unit:piece"
},
"hasAlternatives": false,
"createdOn": "2022-02-03T14:48:54.709Z",
"lastModifiedOn": "2022-02-03T14:48:54.709Z",
"catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04",
"businessPartner": "BPNL50096894aNXY"
}
]
}

Example JSON payload: Submodel "SingleLevelBomAsBuilt" v2.0.0 for a Batch

{
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"childItems": [
{
"quantity": {
"quantityNumber": 25.0,
"measurementUnit": "unit:kilogram"
},
"hasAlternatives": false,
"createdOn": "2022-02-03T14:48:54.709Z",
"lastModifiedOn": "2022-02-03T14:48:54.709Z",
"catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04",
"businessPartner": "BPNL50096894aNXY"
}
]
}

3.4 ASPECT MODEL "TractionBatteryCode"

3.4.1 INTRODUCTION

This semantic model describes a submodel for a digital twin of a traction battery or a respective subcomponent (pack, module or cell). This aspect model provides information about the traction battery code of a battery component. A traction battery code is an identification code according to GB/T 34014-2017 which has to be provided when exporting automotive traction batteries to the People's Republic of China. In addition to the traction battery code, the model also contains classification of the corresponding battery component and all subcomponents.

On the lowest level, the cell level, the model contains only the traction battery code for the cell and the information on the classification which describes if the corresponding part is a cell, a module or a pack. On the middle level, the module level, the model contains the same information for the module (code and classification). In addition to that, however, it also includes a list of the cells information that are assembled into the module. Analogue to this, on pack level, the model contains the information of the pack itself as well as the information of the modules assembled into the pack and the cells assembled into the modules.

By accessing this aspect you can get all traction battery codes that are a part of the corresponding part of the traction battery.

Note: The presented aspect model is in version 1.0.0 and is optional.

3.4.2 SPECIFICATIONS ARTIFACTS

The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification SMT.

This aspect model is written in BAMM 2.0.0 as a modeling language conformant to CX-0003 as input for the semantic deriven workflow.

Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003.

3.4.3 LICENSE

This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons.

3.4.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

urn:bamm:io.catenax.traction_battery_code:1.0.0#TractionBatteryCode

3.4.5 FORMATS OF SEMANTIC MODEL

3.4.5.1 RDF TURTLE

The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations.

TractionBatteryCode v1.0.0 (optional)

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.traction_battery_code/1.0.0/TractionBatteryCode.ttl

The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation.

3.4.5.2 JSON SCHEMA

A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel".

3.4.5.3 AASX

An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to [SMT].

3.4.6 EXAMPLES

EXAMPLE: JSON PAYLOAD: ASPECT MODEL "TractionBatteryCode" FOR A BATTERY CELL
{
"productType": "cell",
"tractionBatteryCode": "X12CCPM27KLPCLE662382320"
}
EXAMPLE: JSON PAYLOAD: ASPECT MODEL "TractionBatteryCode" FOR A BATTERY MODULE
{
"productType": "module",
"tractionBatteryCode": "B54MCPM27KLPCLE6A7519857",
"subcomponents": [
{
"productType": "cell",
"tractionBatteryCode": "X12CCPM27KLPCLE662382320"
},
{
"productType": "cell",
"tractionBatteryCode": "X12CCPM27KLPCLE662382321"
}
]
}
EXAMPLE: JSON PAYLOAD: ASPECT MODEL "TractionBatteryCode" FOR A BATTERY 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"
}
]
}
]
}

4 APPLICATION PROGRAMMING INTERFACES

This section is normative

4.1 NOTIFICATION API

This chapter describes notification API with its relevant API endpoints to be created by each traceability application and their integration into the IDSA Protocol and/or the Eclipse Dataspace Connector (EDC) as a reference implementation. For now, the notification API is limited to the sending and receiving of quality notifications as well as the update of the notification status (following a predefined status model).

4.1.1 PRECONDITIONS AND DEPENDENCIES

Application providers MUST prove their conformity by providing:

  • An openAPI specification of the endpoints described.

  • Examples of the data asset and contract definition structure in their EDC or any other IDS protocol compliant connector.

The Notification API MUST be published towards the network using a Data Asset/Contract Definition in terms of the IDSA Protocol as described by the reference implementation [CX - 0018 Eclipse Data Space Connector (EDC)].

The Eclipse Dataspace Connector as a reference implementation SHOULD BE used and is referenced in this document. Other connectors fulfilling the same standards towards Catena-X MAY be leveraged as well.

It is of importance to mention, that there MUST be an API available behind each of the data offers described in the EDC, which works according to the openAPI specifications description.

Nevertheless, the APIs are OPTIONAL to follow the same structure, as there could even be APIs taking over the job of several of the endpoints mentioned.

The EDC SHOULD act as a reverse proxy towards those APIs, as it holds the Data Offers linked to the respective implemented endpoints.

4.1.2 API SPECIFICATION

4.1.2.1 API-ENDPOINTS

The notification API MUST be implemented as specified in the openAPI documentation as stated here: openAPI

The notification API MUST implement four endpoints similar to:

  • POST /qualityinvestigations/receive
  • POST /qualityinvestigations /update
  • POST /qualityalert /receive
  • POST /qualityalert/update

In fact, it is OPTIONAL to implement the endpoint paths exactly as described above. The reason is that those endpoints are not called from any supply chain partner directly. Rather, they are called from the Eclipse Dataspace Connector (EDC) as part of EDC data assets. In that sense, it is just important to implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body.

The EDCs data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the EDC data assets are of significance, which SHOULD be exposed towards Catena-X through the Data

Offer Catalogues in the EDC or any other IDSA Protocol compatible connector.

4.1.2.2 Available Data Types

The notification API MUST use JSON as the payload transported via HTTP.

4.1.2.3 API resources & endpoints

The HTTP POST endpoints introduced in this standard MUST be called via Data Space Protocol.

The sending and receiving of notifications MUST be built on the basis of HTTP POST endpoints.

4.1.3 EDC DATA ASSET STRUCTURE

4.1.3.1 EDC Data Asset for Notification Receive Endpoint for Quality Investigation Receipt

When using the EDC, the following asset MUST be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X.

  
{
"@context": {},
"asset": {
"@type": "Asset",
"@id": "qualityinvestigationnotification-receipt",
"properties": {
"id": "qualityinvestigationnotification-receipt",
"name": "Asset to receive quality investigations",
"contenttype": "application/json",
"type": "notification.trace.qualitynotification",
"notificationtype": "qualityinvestigation",
"notificationmethod": "receive"
}
},
"dataAddress": {
"@type": "DataAddress",
"baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/qualityinvestigations/receive",
"proxyMethod": "true",
"proxyBody": "true",
"proxyPath": "true",
"type": "HttpData"
}
}

The variable {{httpServerWhichOffersTheHttpEndpoint}} MUST be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/receive MAY align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application.

4.1.3.2 EDC Data Asset for Notification Receive Endpoint for Quality Alert Receipt

When using the EDC, the following asset MUST be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X.

  
{
"@context": {},
"asset": {
"@type": "Asset",
"@id": "qualityalertnotification-receipt",
"properties": {
"id": "qualityalertnotification-receipt",
"name": "Asset to receive quality alerts",
"contenttype": "application/json",
"type": "notification.trace.qualitynotification",
"notificationtype": "qualityalert",
"notificationmethod": "receive"
}
},
"dataAddress": {
"@type": "DataAddress",
"baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/qualityalert/receive",
"proxyMethod": "true",
"proxyBody": "true",
"proxyPath": "true",
"type": "HttpData"
}
}

The variable {{httpServerWhichOffersTheHttpEndpoint}} MUST be set to the HTTP server that offers the endpoint. The path /qualityalerts/receive MAY align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application.

4.1.3.3 EDC Data Asset for Notification Update Endpoint for Quality Investigation Update

When using the EDC the following asset MUST be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X.

  
{
"@context": {},
"asset": {
"@type": "Asset",
"@id": "qualityinvestigationnotification-update",
"properties": {
"id": "qualityinvestigationnotification-update",
"name": "Asset to update quality investigations",
"contenttype": "application/json",
"type": "notification.trace.qualitynotification",
"notificationtype": "qualityinvestigation",
"notificationmethod": "update"
}
},
"dataAddress": {
"@type": "DataAddress",
"baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/qualityinvestigation/update",
"proxyMethod": "true",
"proxyBody": "true",
"proxyPath": "true",
"type": "HttpData"
}
}

The variable {{httpServerWhichOffersTheHttpEndpoint}} MUST be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/update MAY align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application.

4.1.3.4 EDC Data Asset for Notification Update Endpoint for Quality Alert Update

When using the EDC the following asset MUST be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X.


{
"@context": {},
"asset": {
"@type": "Asset",
"@id": "qualityalertnotification-update",
"properties": {
"id": "qualityalertnotification-update",
"name": "Asset to update quality alerts",
"contenttype": "application/json",
"type": "notification.trace.qualitynotification",
"notificationtype": "qualityalert",
"notificationmethod": "update"
}
},
"dataAddress": {
"@type": "DataAddress",
"baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/qualityalert/update",
"proxyMethod": "true",
"proxyBody": "true",
"proxyPath": "true",
"type": "HttpData"
}
}

The variable {{httpServerWhichOffersTheHttpEndpoint}} MUST be set to the HTTP server that offers the endpoint. The path /qualityalerts/update MAY align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application.

4.1.4 ERROR HANDLING

HTTP standard response codes MUST be used.

4.1.4.1 Error Messages & Explanation

The following http response codes MUST be defined for HTTP POST endpoint to receive a quality alert and quality investigation notification:

CodeDescription
201Quality notification was received successfully
400Request body was malformed
401Not authorized
403Forbidden
405Method not allowed
409Could not accept the send quality notification, because a quality notification with that notificationId already exists
422Could not accept the send quality notification even though it is syntactically correct. The quality notification is not accepted, because of semantic reasons (e.g., an affected item is not known by the receiver)

The following http response codes MUST be defined for HTTP POST endpoint to update a quality alert and quality investigation notification:

CodeDescription
200Quality notification was updated successfully
400Request body was malformed
401Not authorized
403Forbidden
404Could not update the quality notification, because a quality notification with that notificationId does not exist
405Method not allowed
422Could not update the quality notification even though the request is syntactically correct. The quality notification update is not accepted, because of semantic reasons (e.g., status cannot be changed)

4.1.5 EXAMPLES

EXAMPLE 1: QUALITY INVESTIGATION

I as a customer discover a quality issue during assembly with several parts of a specific supplier. I want to inform my supplier to perform a quality investigation on his side and want to communicate this data securely and sovereign to him.

EXAMPLE 2: QUALITY ALERT

I as a supplier discover a problem with specific batches or serialized parts on my end affecting also parts already shipped. I want to communicate this data securely and sovereign to my customers.

5 PROCESSES

This section is normative

5.1 NOTIFICATION PROCESS

This chapter describes the minimum requirements for the notification process and does not go beyond the sending and receiving of quality notifications.

The process takes place in between traceability applications or application stacks, and the focus is on minimal interaction, which MUST be supported by all applications participating in a quality notification or quality investigation scenario.

Application internals like user journeys, process steps or workflows in an application are not standardized within Catena-X, and therefore omitted.

5.1.1 ACTORS AND ROLES

Catena-X does not standardize user-roles at the moment. The actors are traceability applications of the companies in a supply chain.

5.1.2 PROCESS REPRESENTATION

The exchange of notifications follows the IDSA protocol.

On top, a notification state model has been described.

5.1.2.1 Notification State Model

The notification itself has various states. The states and their cycle are described in the following picture (Figure 1):

CX0125_Process.jpg

Figure 1: Description of Process

The state of a notification MUST be exchanged via the Notification API.

5.1.2.2 Processes for Sending and Updating Notifications

Below the sequence for sending and updating of notifications between (traceability) applications is shown in UML sequence diagrams In all cases, HTTP POST requests MUST be used. The corresponding HTTP endpoints are described in the Traceability Notification API specification.

To read the UML sequence diagrams correctly, some remarks below:

  • The shown Notification EDC Adapter is not mandatory. It is just one option to send a notification via the EDC control and data plane. It is important, that a similar functionality must be provided/implemented by the (traceability) application vendor. The Notification EDC Adapter or a similar component / functionality will not be provided as a central service from Catena-X.

  • To discover where a notification MUST be sent to, the (traceability) application MUST resolve the BPN of the receiver. This can either happen through the (traceability) application holding this information in its data model, or it could - alternatively - also be resolved e.g. via a lookup of the digital twin in the central asset administration shell (AAS) registry or by using services from the BPDM use case.

  • The resolution of the EDC URL for a given BPN SHOULD be done via the EDC Discovery Service API [CX-0001]. The entry for each EDC into this Discovery Service is done via the Catena-X Portal.

  • In each UML sequence diagram the step [01] describes the publishing of the notification endpoints as described in the above sections.

5.1.2.2.1 Sending and receiving of a quality investigation

Below, the UML sequence diagram to send and receive a quality investigation is depicted.

In addition to the above-mentioned general remarks, the following remark has to be mentioned:

  • The status transition from SENT to RECEIVED MUST be done by the

    sender once it received the Http status code 201 from the receiver

CX0125_SendAndReceive_2.jpg

Figure 2: Send and Receive Quality Investigation

5.1.2.2.2 Sending and receiving of a quality alert (optional)

Below, the UML sequence diagram to send and receive a quality alert is depicted.

In addition to the above-mentioned general remarks, the following remark has to be mentioned:

  • The status transition from SENT to RECEIVED MUST be done by the

    sender once it received the Http status code 201 from the receiver

CX0125_SendAndReceive_3.jpg

Figure 3: Send and Receive Quality Alert

5.1.2.2.3 Update of a quality investigation

Below, the UML sequence diagram to update a quality investigation is depicted.

CX0125_UpdateQuality_4.jpg

Figure 4: Update Quality Investigation

5.1.2.2.4 Update of a quality alert

Below, the UML sequence diagram to update a quality alert is depicted.

CX0125_UpdateQualityAltert_5.jpg

Figure 5: Update Quality Alert

6 REFERENCES

6.1 NORMATIVE REFERENCES

This section is normative

  • CX-0018 ECLPISE DATA SPACE CONNECTOR (EDC) 2.0.1
  • CX-0127 INDUSTRY CORE - PART INSTANCE 1.0.0
  • CX-0019 ASPECT MODEL SERIAL PART 2.0.0
  • CX-0021 ASPECT MODEL BATCH 2.0.0
  • CX-0020 ASPECT MODEL SINGLE LEVEL BOM AS BUILT 2.0.0
  • EDC Reference Implementation - https://github.com/eclipse-tractusx/tractusx-edc

6.2 NON-NORMATIVE REFERENCES

This section is non-normative

6.3 REFERENCE IMPLEMENTATIONS

This section is non-normative

ANNEXES

FIGURES

This section is non-normative

TABLES

This section is non-normative

Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit here.

Footnotes

  1. https://catena-x.net/de/standard-library 2