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)
SerialPart v2.0.0 (optional)
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)
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)
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:
| Code | Description |
|---|---|
| 201 | Quality notification was received successfully |
| 400 | Request body was malformed |
| 401 | Not authorized |
| 403 | Forbidden |
| 405 | Method not allowed |
| 409 | Could not accept the send quality notification, because a quality notification with that notificationId already exists |
| 422 | Could 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:
| Code | Description |
|---|---|
| 200 | Quality notification was updated successfully |
| 400 | Request body was malformed |
| 401 | Not authorized |
| 403 | Forbidden |
| 404 | Could not update the quality notification, because a quality notification with that notificationId does not exist |
| 405 | Method not allowed |
| 422 | Could 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):
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
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
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.
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.
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
-
The Traceability KIT and sub-KITs will include further information on EDC data asset structures, Digital Twin Submodel examples and API calls to be made.
-
[SMT] How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf
6.3 REFERENCE IMPLEMENTATIONS
This section is non-normative
ANNEXES
FIGURES
This section is non-normative
TABLES
This section is non-normative
Legal
Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit here.