diff --git a/docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md b/docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md index 74a8f4a47ee..8f866282926 100644 --- a/docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md +++ b/docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md @@ -1,7 +1,7 @@ --- id: Specification Traceability Kit title: Specification -description: 'Traceability Kit' +description: "Traceability Kit" sidebar_position: 4 --- @@ -14,6 +14,7 @@ Development View of the Kit. --> + ## API Specifications ### Unique ID Push Notifications @@ -27,6 +28,7 @@ All endpoints as well as the schema of the notification below are described in d [Publish Traceability Data Offers at EDC](#publish-traceability-data-offers-at-edc) + ## Sample Data In the following, example data for submodels are provided. @@ -114,11 +116,11 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se ### As Built Submodels Sample Data -#### Submodel SerialPartTypization +#### Submodel SerialPart -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) -##### Submodel "SerialPartTypization" for a Vehicle +##### Submodel "SerialPart" for a Vehicle ```json { @@ -127,6 +129,10 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se "key": "manufacturerId", "value": "BPNL7588787849VQ" }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, { "key": "partInstanceId", "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" @@ -149,7 +155,7 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -##### Submodel "SerialPartTypization" for a Serialized Part (Non-Vehicle) +##### Submodel "SerialPart" for a Serialized Part (Non-Vehicle) ```json { @@ -182,45 +188,45 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -#### Submodel AssemblyPartRelationship +#### Submodel SingleLevelBomAsBuilt -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0) -##### Submodel "AssemblyPartRelationship" for a Serialized Part +##### Submodel "SingleLevelBomAsBuilt" for a Serialized Part ```json { "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childParts": [ + "childItems": [ { - "lifecycleContext": "AsBuilt", "quantity": { "quantityNumber": 1.0, "measurementUnit": "unit:piece" }, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04" + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" } ] } ``` -##### Submodel "AssemblyPartRelationship" for a Batch +##### Submodel "SingleLevelBomAsBuilt" for a Batch ```json { "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childParts": [ + "childItems": [ { - "lifecycleContext": "AsBuilt", "quantity": { "quantityNumber": 25.0, "measurementUnit": "unit:kilogram" }, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04" + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" } ] } @@ -228,7 +234,7 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se #### Submodel Batch -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) ##### Submodel "Batch" for a Batch of Raw Material @@ -247,10 +253,8 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", "partTypeInformation": { "manufacturerPartId": "123-0.740-3434-A", - "customerPartId": "PRT-12345", "classification": "product", "nameAtManufacturer": "PA66-GF30", - "nameAtCustomer": "Polyamide" } } ``` @@ -294,7 +298,78 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -> Please note that if a just-in-sequence part is also a serialized part SerialPartTypization should be used instead. +> Please note that if a just-in-sequence part is also a serialized part SerialPart should be used instead. + +#### Submodel TractionBatteryCode + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0) + +##### Submodel "TractionBatteryCode" for a Battery Cell + +```json +{ + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" +} +``` + +##### Submodel "TractionBatteryCode" for a Battery Module + +```json +{ + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382321" + } + ] +} +``` + +##### Submodel "TractionBatteryCode" for a Battery Pack + +```json +{ + "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" + } + ] + } + ] +} +``` ## Reference Implementation @@ -306,29 +381,29 @@ For a reference implementation, take a look at the open-source Trace-X app. More ### Data Provisioning -The following diagram shows a basic data processing flow how a comany's internal data can be transformed into a Traceability-compliant format. It depicts the necessary steps as well as where communication with other services, e.g., Catena-X network services like the Digital TWin Registry, are necessary. Any implementation of this implementation specification can deviate from this basic flow as it's just one way to do it. But it should give a basic idea what the essential steps are. +The following diagram shows a basic data processing flow how a comany's internal data can be transformed into a Traceability-compliant format. It depicts the necessary steps as well as where communication with other services, e.g., Catena-X network services like the Digital Twin Registry, are necessary. Any implementation of this implementation specification can deviate from this basic flow as it's just one way to do it. But it should give a basic idea what the essential steps are. ![Basic Data FLow](../assets/data_provisioning_data_flow.png) #### Register Digital Twins for Traceability -In Traceability, digital twins for different types of parts are registered at the digital twin registry, e. g. serialized parts, batches, JIS parts or catalog parts. +In Traceability, digital twins for different types of parts are registered at a Digital Twin Registry, e. g. serialized parts, batches, JIS parts or catalog parts. Basic information about how to register digital twins in Catana-X are described in the standard [CX-0002 Digital Twins in Catena-X](https://catena-x.net/de/standard-library). > :raised_hand: **Unique ID Push** -Once a digital twin was created, optionally a Unique ID Push notification can be send to the customer of the part of batch to inform them that a new digital twin is available. +> Once a digital twin was created, optionally a Unique ID Push notification can be send to the customer of the part of batch to inform them that a new digital twin is available. The following general conventions apply for all these digital twins: -- identification: The AAS ID must be a UUIDv4 in URN format: `urn:uuid:` -- globalAssetId: The Unique ID of the real-world part for which a digital twin is created. +- id: The AAS ID must be a UUIDv4 in URN format: `urn:uuid:`; +- globalAssetId: the Unique ID of the real-world part for which a digital twin is created. > :warning: The AAS ID is not the same id as the Catena-X Unique ID, although they have the same format (UUID) and therefore look the same. A Unique ID identifies real-world parts, whereas a AAS ID identifies a digital twin of such a part. So, don't use the same value for Unique ID and AAS ID. ##### Property specificAssetIds -For Traceability, we define some specificAssetIds as mandatory. Mandatory specific asset IDs are used to lookup or search for digital twins. This is a required step by a customer of a part to connect the digital twins of their parts with the digital twins of the suppliers' child parts. To a customer, only the information printed on a real-world part is available and can be used for the lookup. Mandatory specific asset IDs ensure that at least this information is available for the digital twin. +For Traceability, we define some specific asset IDs as mandatory. Mandatory specific asset IDs are used to lookup or search for digital twins. This is a required step by a customer of a part to connect the digital twins of their parts with the digital twins of the suppliers' child parts. To a customer, only the information printed on a real-world part is available and can be used for the lookup. Mandatory specific asset IDs ensure that at least this information is available for the digital twin. -The following conventions for specificAssetIds apply to all digital twins: +The following conventions for specific asset IDs apply to all digital twins: @@ -349,35 +424,14 @@ The following conventions for specificAssetIds apply to all digital twins: - - + @@ -386,55 +440,188 @@ If no access control shall be applied, externalSubjectId must be omitted (no acc **For serialized parts, additionally the following conventions apply:** | Key | Availability | Description | Type | -|:---------------|:-------------|:---------------------------------------------------------------------------------------------|:-------| +| :------------- | :----------- | :------------------------------------------------------------------------------------------- | :----- | | partInstanceId | Mandatory | The serial number of the part from the manufacturer. | String | | van | Optional | **Only for vehicles:** The pseudonymized vehicle identification number (VIN) of the vehicle. | String | **For batches, additionally the following conventions apply:** | Key | Availability | Description | Type | -|:---------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------| +| :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | | batchId | Optional | The number of the batch from the manufacturer. | String | -| partInstanceId | Mandatory | Also the number of the batch from the manufacturer.

For **Release 3.0**, we also use the batch number as partInstanceId. This makes looking up digital twins for serialized parts and batches easier as a data consumer only has to specify the partInstanceId no matter if they are looking up a serialized part or a batch. Otherwise, the data consumer would need to know for what type of digital twin it is looking for or it would have to look for both until a match is found. | String | +| partInstanceId | Mandatory | Also the number of the batch from the manufacturer.

Currently, we also use the batch number as partInstanceId. This makes looking up digital twins for serialized parts and batches easier as a data consumer only has to specify the partInstanceId no matter if they are looking up a serialized part or a batch. Otherwise, the data consumer would need to know for what type of digital twin it is looking for or it would have to look for both until a match is found. | String | **For just-in-sequence (JIS) parts, additionally the following conventions apply:** -| Key | Availability | Description | Type | -|:-------------------|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------| -| parentOrderNumber | Optional | A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. | String | -| jisNumber | Mandatory | A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. | String | -| jisCallDate | Optional | The date of the just-in-sequence call-off as stated on the call-off document itself.
The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm` | Date | -| partInstanceId | Mandatory | A composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (ifavailable). This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts. | String | +| Key | Availability | Description | Type | +| :---------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | +| parentOrderNumber | Optional | A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. | String | +| jisNumber | Mandatory | A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. | String | +| jisCallDate | Optional | The date of the just-in-sequence call-off as stated on the call-off document itself.
The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm` | Date | +| partInstanceId | Mandatory | A composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (ifavailable). This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts. | String | > :raised_hand: **Lookup of Digital Twins** -The lookup for parts can use the customerPartId or the manufacturerPartId. Both, manufacturer and customer must agree upon what part id will be used for the lookup. Otherwise, when the customer would use the customerPartId for the lookup, but the manufacturer would only provide the manufacturerPartId in its digital twins, the lookup would fail every time. **This is decision that a customer must agree upon with each of their suppliers individually.** +> The lookup for parts can use the customerPartId or the manufacturerPartId. Both, manufacturer and customer must agree upon what part id will be used for the lookup. Otherwise, when the customer would use the customerPartId for the lookup, but the manufacturer would only provide the manufacturerPartId in its digital twins, the lookup would fail every time. **This is decision that a customer must agree upon with each of their suppliers individually.** + +##### Authorization: Visbility of Specific Asset IDs in the DTR + +To enforce a strict need-to-know (and prevent data from being exposed to non-authorized parties), the visibility of entries in the attribute `specificAssetIds` must be protected, i.e.,their visibility must be restricted to authorized parties only. For that, the attribute `externalSubjectId` must be used. Detailed information about this can be found in the [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/category/digital-twin-kit). ##### Submodel Descriptors -The following general conventions apply for all submodel descriptors: - -- `identification`: The submodel ID must be a UUIDv4 in URN format: "urn:uuid:<UUIDv4>" -- `idShort`: The name of the aspect model in camel case, e.g. for aspect SerialPartTypization: "serialPartTypization". -- `endpoints`: For access of submodels via EDC and AAS a new interface type EDC-AAS must be defined. - - `interface`: The value must be "EDC" - - `endpointAddress`: The endpoint address must have the following format: `http://provider.controlplane:port//submodel?content=value&extent=WithBLOBValue` - - `provider.controlplane:port`: server and port of the EDC that is providing the submodel - - `EDC Asset ID`: The EDC asset id under which the submodel was registered in the EDC. It must have the following format `-` - - `AAS ID`: The id of the digital twin (identification property in the AAS descriptor) - - `Submodel`: The id of the submodel (identification property in the submodel descriptor) - - `/submodel`: This method from the AAS Shell Interface that is invoked via the EDC. - - `content=value&extent=WithBLOBValue`: This are currently required parameters when requesting payload via the AAS standard from an EDC - - `endpointProtocol`: The value must be `IDS/ECLIPSE DATASPACE CONNECTOR` - - `endpointProtocolVersion`: The value must be `0.0.1-SNAPSHOT` - -> :raised_hand: **AAS Submodel Descriptor Endpoints** -The endpoint (endpointAddress) in the submodel descriptor cannot be used directly to contact the EDC and access the data. The endpoint has to be re-written as it combines EDC and AAS information. The AAS API Wrapper does that automatically when using it, i.e., it fetches the endpoint from the AAS Registry and re-writes it in a way to a Catena-X EDC with an AAS server in the background can process the query. +General conventions for submodel descriptors can be found in the standard [CX-0002 Digital Twins in Catena-X](https://catena-x.net/de/standard-library). This section is based on it and it is recommended to read it first. In this KIT, we extend this standard with some additional conventions. + +Submodel descriptors MUST be compliant to the following additional conventions: + +- `id`: The submodel ID must be a UUIDv4 in URN format: "urn:uuid:<UUIDv4>"; +- `idShort`: the name of the aspect model in camel case, e.g. for aspect SerialPart: "serialPart". + +The actual access information for the EDC is part of the endpoint attribute in the submodel descriptor. + +```json +{ + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/{path}/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } +} +``` + +The following conventions apply for the endpoint: + +- `interface`, `endpointProtocol`, `endpointProtocolVersion`, `subprotocol`, `subprotocolBodyEncoding`, and `securityAttributes` are set as defined in the [CX-0002 standard](https://catena-x.net/de/standard-library). +- `href`: The endpoint address for the logical operation GetSubmodel that is invoked by a data consumer to get the submodel. It must have the following format: + - `edc.data.plane`: Server and port of the EDC data plane that is providing the submodel. + - `{path}`: This `{path}` string is forwarded to the backend data service by the EDC data plane. Together with the EDC asset information (see below) it must contain all information for the backend data service to return the requested submodel. The actual path depends on the type of backend data service that the data provider uses to handle the request. More details follow below. + - `/submodel`: This `/submodel` string is also forwarded to the backend data service. As AAS Profile SSP-003 of the Submodel Service Specification is mandatory for release 3.2, `href` must have the suffix "/submodel" representing the invokation of the GetSubmodel operation. +- `subprotocolBody`: a semicolon-separated list of parameters used to negotiate the required contract agreement. + - `id=123`: The ID of the EDC asset for which a contract negitiation should be intiated. This ID is also called dataset ID as it is stored as `https://www.w3.org/ns/dcat/dataset.@id` in a catalog entry. This ID must be set by the data provider when creating the asset. Do not confuse this EDC asset ID (dataset ID) with other IDs that might be defined additionally for an EDC asset, e.g., `https://w3id.org/edc/v0.0.1/ns/id` (often refered to as `edc:id`). + - `dspEndpoint`: Server and port of the EDC control plane used for contract negotiation. + +> :raised_hand: **Backend Data Service for Submodels** +According to [CX-0002](https://catena-x.net/de/standard-library), the backend data service identified via `href`and the filter criteria in `subprotocolBody` MUST be conformant to the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification and must at least support the logical operation GetSubmodel. In release 3.2, only the logical parameter Content=Value must be supported via path suffix "/submodel/$value". This might change in later releases. + +With this approach, the EDC asset structure must no longer follow the "one EDC asset per submodel" rule (as in Release 3.1 and before), but gives data providers more flexibility how to create EDC assets for their digital twins and submodels based on how they use `{path}`. + +###### Option 1: Same EDC Asset Structure as in Release 3.1 + +Submodels of digital twins are registered in the EDC the same way as for release 3.1: One EDC asset is created for every submodel of a digital twin. + +- `href` must have the following format: `http://edc.data.plane/submodel` +- `subprotocolBody` must have the following format: `id={edcAssetId};dspEndpoint=http://edc.control.plane` +- edcAssetId is the id of the EDC asset for the submodel. It must have the following format "{aasIdentifier}-{submodelIdentifier}" with + - aasIdentifier: the id of the digital twin (id property in the AAS descriptor) + - submodelIdentifier: the id of the submodel (id property in the submodel descriptor) + +Here's an example how such a submodel descriptor could look like: + +```json +"submodelDescriptors": [ + { + "idShort": "serialPart", + "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=urn:uuid:75e98d67-e09e-4388-b2f6-ea0a0a642bfe-urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0;dspEndpoint=http://edc.control.plane/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } + } + ] + } +] +``` + +In this example, the `path` part in the `href` is empty, as the EDC asset referenced in `subprotocolBody` directly points to a service returning the correct submodel (set up correctly with its dataAddress in the data provider's EDC). + +###### Option 2: EDC Asset Structure on Catalog Part Level + + A data provider can link several submodel endpoints to the same EDC asset (referenced by its id). This allows to create only one EDC asset (per aspect model) for a catalog part and link all submodels (of the same aspect model) for serialized parts of the catalog part to the same EDC asset. The data provider would still need to create separate EDC assets per aspect model as in most cases different usage policies are used for aspect models. + +If a data provider no longer creates EDC assets on the level of submodels, the EDC can no longer authorize a request on a submodel-level. For example: If EDC assets are created per catalog part, the EDC can only authorize if the requestor is allowed to see parts of these type in general; if the requestor is allowed to see a actual serialized part, must be authorized by the backend data service executing the request. + +Here's an example how such a submodel descriptor could look like: + +```json +"submodelDescriptors": [ + { + "idShort": "serialPart", + "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/urn%3Auuid%3A75e98d67-e09e-4388-b2f6-ea0a0a642bfe-urn%3Auuid%3A7effd7f4-6353-4401-9547-c54b420a22a0/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=urn:uuid:1475f313-0a83-4e2b-b705-a100eebcb7d7;dspEndpoint=http://control-plane.edc.catena-x.net/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } + } + ] + } +] +``` + +The path part of the `href` property contains the information for the backend data service which digital twin's submodel to return while the EDC asset ID is used for several endpoints. The path part here is just an example as it depends on the type of backend data service the data provider uses. + +The above options are only two examples how a submodel's endpoint can be created. As long as it's compliant with the above conventions (including [CX-0002](https://catena-x.net/de/standard-library)) a data provider can also use any other EDC asset structure. + +###### Data Consumption with AAS Submodel Descriptor Endpoints + +The endpoint `href` in the submodel descriptor cannot be used directly to contact an EDC and access the data in Catena-X. + +- A data consumer must first identify the protocol that must be used to retrieve the submodel data based on the `subprotocol`. For data transfers in Catena-X, this is "DSP" +- With `href`, the data consumer calls the local operation GetSubmodel as specified by the suffix "/submodel". As only the logical parameter "Content" must be supported in release 3.2, "/$value" must be appended to `href` by the data consumer. + If the `href` endpoint is called with operations or parameter values not yet supported, the error response 501 "Not Implemented" must be returned according to [CX-0002](https://catena-x.net/de/standard-library). +- Then, the data consumer must use the information in the `subprotocolBody` to perform a contract negotiation for the EDC asset referenced by `id` with the EDC control plane of the data provider specified by `dspEndpoint`. +- Finally, using the id from the contract agreement with the control plane, the data consumer initiates the data transfer with the EDC data plane of the data provider referenced in the `href`. The enriched path part of the `href` (see bullet point 2) is passed to data provider data plane by the data consumer as a parameter for the backend data service that actually executes the request and returns the submodel. + +All these steps must be handled by the data consumer that want to retrieve the submodel data of a digital twin. #### Lookup for Digital Twins in the Digital Twin Registry For a data provider, there are currently the following steps where they have to lookup digital twins of other partners in the Catena-X network. -- The data provider must use the local IDs for a serialized part or batch (manufacturer, part number, serial or batch number) and for a just-in-sequence part (manufacturer, parentOrderNumber, jisNumber, jisCallDate) to lookup the AAS ID of the digital twin of this serialized part, batch or just-in-sequence part. The AAS descriptor with this ID contains the Unique ID of the serialized part, batch or just-in-sequence (as globalAssetId) that is used to create the AssembyPartRelationship submodel. +- The data provider must use the local IDs for a serialized part or batch (manufacturer, part number, serial or batch number) and for a just-in-sequence part (manufacturer, parentOrderNumber, jisNumber, jisCallDate) to lookup the AAS ID of the digital twin of this serialized part, batch or just-in-sequence part. The AAS descriptor with this ID contains the Unique ID of the serialized part, batch or just-in-sequence (as globalAssetId) that is used to create SingleLevelBomAsBuilt submodel. - The data provider must use the local IDs for a catalog part (manufacturer, part number) to lookup the AAS ID of the digital twin of this catalog part. The AAS descriptor with this ID contains the Unique ID of the catalog part (as globalAssetId) that is used to create the SingleLevelBoMAsPlanned submodel. @@ -445,7 +632,7 @@ For a data consumer, there are currently the following steps where they have to ##### Lookup up a Digital Twin with Local IDs -The local IDs of a serialized part (manufacturer, part number, serial number) are stored as specificAssetIds in the AAS descriptor of the digital twin. From the Digital Twin Registry API, the following function can be used for this lookup `GET /lookup/shells`. +The local IDs of a serialized part (manufacturer, part number, serial number) are stored as specific asset IDs in the AAS descriptor of the digital twin. From the Digital Twin Registry API, the following function can be used for this lookup `GET /lookup/shells`. All Asset identifier key-value-pairs used as parameter to this lookup function are combined using AND. An example query would look like this: `https://URL/registry/lookup/shells?assetIds=%5B%7B%22key%22%3A%20%22manufacturerId%22,%22value%22%3A%20%22BPNL7588787849VQ%22%7D,%7B%22key%22%3A%20%22manufacturerPartId%22,%22value%22%3A%20%2295657362-83%22%7D,%7B%22key%22%3A%20%22partInstanceId%22,%22value%22%3A%20%22NO-574868639429552535768526%22%7D%5D` @@ -470,28 +657,26 @@ All Asset identifier key-value-pairs used as parameter to this lookup function a The lookup (for serialized parts/batches as well as catalog parts) can use the customer or the manufacturer part id (manufacturerPartId or manufacturerPartId). -- For a digital twin, adding the customer part id to the specificAssetId property is optional (see (TRS) Create Digital Twins for Serialized Parts and Batches incl. Submodels). The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the specifiAssetId property for easier lookup (by customers). +- For a digital twin, adding the customer part id to the specific asset IDs is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the specifiAssetId property for easier lookup (by customers). - A customer that wants to do a lookup for a supplier's digital twin, must first decide what id they want to use for the lookup. This depends on the information that is available to them. - If the customer knows the manufacturer part id, they should use the manufacturer part id for the lookup as the manufacturer part id is guaranteed to be available in the digital twin (as the manufacturer part id is a mandatory property). - - If the customer does not know the manufacturer part id, they must use the customer part id (i.e., their own part id). In that case they must make sure that their suppliers register their digital twins with this information (as the customer part id is optional) as part of the specificAssetId property. This is decision that a customer must agree upon with each of their suppliers individually. + - If the customer does not know the manufacturer part id, they must use the customer part id (i.e., their own part id). In that case they must make sure that their suppliers register their digital twins with this information (as the customer part id is optional) as part of the specific asset IDs. This is decision that a customer must agree upon with each of their suppliers individually. As a result, the AAS ID of the digital twin with this local IDs is returned. The AAS ID can then be used to retrieve details about the digital twin, i.e. the digital twin's AAS descriptor including submodel descriptors. **Example result for looking up a digital twin with local IDs:** ```json -[ - "urn:uuid:c227a880-b82b-40f7-846c-3942ddf26c29" -] -```` +["urn:uuid:c227a880-b82b-40f7-846c-3942ddf26c29"] +``` Note that this query can return more than one AAS ID depending on the local IDs uniquely identifying a digital twin or not. -For Release 3.0, even if more than one digital twin is returned in a lookup, these digital twins should have different submodels assigned to them. These submodels should be disjunct and not overlap. This means that you can use the submodel to filter out the correct digital twin. +Currently, even if more than one digital twin is returned in a lookup, these digital twins should have different submodels assigned to them. These submodels should be disjunct and not overlap. This means that you can use the submodel to filter out the correct digital twin. - If there are returned more than one digital twin with the same submodel (based on their semanticId), this is considered an error. Processing should be canceled and an error message should be reported. -The next section describes to to modify the lookup to additionally restrict the results to digital twins with a specific submodel type based on it's semanticId. +The next section describes to modify the lookup to additionally restrict the results to digital twins with a specific submodel type based on it's semanticId. #### Unique ID Push Notifications @@ -511,7 +696,7 @@ Secondly, EDCs are being used for the exchange and it is currently required to o ##### Unique ID Push Process Overview -How the actual process is triggered is application specific. It is recommended to to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication). +How the actual process is triggered is application specific. It is recommended to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication). The Unique ID push is initiated by the supplier (acting as sender) towards their customer (acting as receiver). Since the Unique ID of the asset (i.e., serial unit / batch) is unknown in the logistics process, the message needs to include local identifiers to be matched towards the information from the delivery documents and furthermore the internal data of the recipient's traceability solution. @@ -519,9 +704,7 @@ Upon receipt of the message, the customer needs to match the local identifiers w - If there is an object for incoming deliveries, this event could be updated. Alternatively, if only production events are tracked, the data could be integrated at this point into the data provisioning pipeline's data structure for consumed materials. -- In the end this enables the customer to integrate the child parts into the AssemblyPartRelationship aspect. - -In the end this enables the customer to integrate the child parts into the AssemblyPartRelationship aspect. +- In the end this enables the customer to integrate the child parts into the SingleLevelBomAsBuilt aspect. ![Unique ID Push Process](../assets/unique_id_push_process.png) @@ -542,7 +725,7 @@ participant "BPDM API" as BPM order 4 end box box "Customer Landscape" #lightyellow -participant "EDC Customer" as EDCCust order 5 +participant "EDC Customer" as EDCCust order 5 participant "Data Provisioning Customer" as TraceCust order 6 end box @@ -576,20 +759,20 @@ The notifications send to inform a customer about the creating of a new digital All endpoints as well as the schema of the notification below are described in detail in the [Unique ID Push API documentation](Unique%20ID%20Push%20API/unique-id-push-notification-api). -> Adding the customer part id to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the notification. +> Adding the customer part id to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, in case the manufacturer knows the customer and the corresponding customer part id of its part though, it is required to always add the customer part id to the notification. ##### Notification Receiver (Customer) Here is a short overview what the receiver has to do when they want to support Unique Id Push notifications. This is an optional feature. -- The Receiver in this scenario is the customer of a part. -- The Receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured. +- The receiver in this scenario is the customer of a part. +- The receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured. - The EDC in which the notification EDC asset was created must be registered at the Discovery Service (so that the sender can find the partner's EDC which should receive notifications) - When the Receiver receives a Unique Id Push notification, it must process this notification after it was received by the EDC (in a Backend Data Service) - How the Receiver processes the notification is up to them, but the following steps are recommended: - Verify the correctness of the data in the notification (i.e., the receiver is actually the customer of this part). - Store the notification data for later. - - Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to the digital twin registry. + - Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to a supplier's Digital Twin Registry. ###### EDC Asset @@ -615,7 +798,7 @@ In general, a data provider is free to decide which usage policies to define for Keep in mind that usage policies currently aren't technically enforced by the EDC or other components. > :raised_hand: **Usage Policy for Unique ID Push** -The Unique ID push notification endpoints are protected with a purpose-based usage policy and "R3-1_UniqueIDPush" as purpose. +> The Unique ID push notification endpoints are protected with a purpose-based usage policy and "R3-1_UniqueIDPush" as purpose. ###### Backend Data Service to Process Unique ID Push Notifications @@ -637,51 +820,50 @@ There should only be one EDC which provides the notification EDC asset for Uniqu #### Creating Submodels for Digital Twins -Submodels for Traceability are mostly easy to create by transforming a company's internal data into the target aspect model, i.e. SerialPartTypization or Batch. Transformations are mostly straightforward in these cases. +Submodels for Traceability are mostly easy to create by transforming a company's internal data into the target aspect model, i.e. SerialPart or Batch. Transformations are mostly straightforward in these cases. The only special step in creating these two submodels is the initial creation of the Unique ID for the corresponding serialized parts or batches. -##### Creation of Submodel AssemblyPartRelationship +##### Creation of Submodel SingleLevelBomAsBuilt -The creation of the submodel AssemblyPartRelationship is more complicated. This submodel contains the Unique ID of the manufacturer's part (attribute catenaXId) which is created - as described above - when the part's SerialPartTypization or Batch submodel is created. But it also contains the Unique IDs of the built-in parts (attributes childParts.childCatenaXId), as shown in the following example: +The creation of the submodel SingleLevelBomAsBuilt is more complicated. This submodel contains the Unique ID of the manufacturer's part (attribute catenaXId) which is created - as described above - when the part's SerialPart or Batch submodel is created. But it also contains the Unique IDs of the built-in parts (attributes childItems.catenaXId), as shown in the following example: ```json { "catenaXId": "urn:uuid:d261e0fa-36f5-4128-875e-0f5735f5a535", - "childParts": [ + "childItems": [ { "quantity": { "quantityNumber": 1, "measurementUnit": "unit:piece" }, - "lifecycleContext": "AsBuilt", "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:9dc1b6fb-94e7-4911-9e39-abf06c4941d2" + "catenaXId": "urn:uuid:9dc1b6fb-94e7-4911-9e39-abf06c4941d2", + "businessPartner": "SingleLevelBomAsBuilt" }, { "quantity": { "quantityNumber": 1, "measurementUnit": "unit:piece" }, - "lifecycleContext": "AsBuilt", "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d17bbf68-6cb7-4045-b3ae-67f41403d098" + "catenaXId": "urn:uuid:d17bbf68-6cb7-4045-b3ae-67f41403d098", + "businessPartner": "SingleLevelBomAsBuilt" } ] } - ``` -For the build-in parts (child parts), their Unique ID is not known to the manufacturer initially. Only know are the local ids that are printed on the physical part (serialized part or batch), i.e., manufacturer (BPN), manufacturer part id and serial or batch number. To get the Unique ID of a built-in part, a data provider therefore has to do the follwoing: +For the build-in parts (child items), their Unique ID is not known to the manufacturer initially. Only know are the local ids that are printed on the physical part (serialized part or batch), i.e., manufacturer (BPN), manufacturer part id and serial or batch number. To get the Unique ID of a built-in part, a data provider therefore has to do the following: - Get all necessary local ids for the built-in part: - manufacturer (BPN), manufacturer part id and serial number for serialized parts - manufacturer (BPN), manufacturer part id and batch number for batches - The next step is about getting the Unique ID of all built-in parts. There are two ways: - Unique IDs might for built-in parts might already be available locally if Unique ID Push is supported by the data provider and the suppliers of the built-in parts. - - Query the Digital Twin Registry to find the digital twin for this built-in part + - Query a supplier's Digital Twin Registry to find the digital twin for this built-in part ###### Unique ID Push @@ -689,31 +871,29 @@ Once the digital twin was created, optionally a Unique ID Push notification can For more information, see [Unique ID Push Notifications](#unique-id-push-notifications) -###### Query the Digital Twin Registry to find the digital twin for this built-in part +###### Query a Digital Twin Registry to find the digital twin for this built-in part -- Querying digital twins is described in (TRS) Lookup for Digital Twins at the Digital Twin Registry +- Querying digital twins is described in [Lookup for Digital Twins in the Digital Twin Registry](#lookup-for-digital-twins-in-the-digital-twin-registry) - Note that the query parameters differ depending on what type of digital twin is looked up. - - For Release 3.0 though, no matter if you want to lookup serialized parts or batches, you can use partInstanceId (using the serial number or the batch number as search parameter value). - - For Batch digital twins, the key batchId might be provided optionally. As this key is not mandatory for Release 2, you cannot rely on this key being available when looking for Batch digital twins. - - To understand why, take a look at how these digital twins are created, especially their specificAssetIds: (TRS) Create Digital Twins for Serialized Parts and Batches incl. Submodels + - Currently though, no matter if you want to lookup serialized parts or batches, you can use partInstanceId (using the serial number or the batch number as search parameter value). + - For Batch digital twins, the key batchId might be provided optionally. As this key is not mandatory currently, you cannot rely on this key being available when looking for Batch digital twins. + - To understand why, take a look at how these digital twins are created, especially their specific asset IDs: [Creating Submodels for Digital Twins](#creating-submodels-for-digital-twins) - The result of this query will be the AAS ID of the digital twin. -- Use this AAS ID to get the AAS Descriptor including all Submodel Descriptors of this digital twin. The AAS Descriptor contains the Submodel Descriptor SerialPartTypization or Batch (depending on the digital twin type). -- Fetch the submodel SerialPartTypization or Batch (depending on the digital twin type) from the EDC that is referenced in the corresponding Submodel Descriptor. +- Use this AAS ID to get the AAS Descriptor including all Submodel Descriptors of this digital twin. The AAS Descriptor contains the Submodel Descriptor SerialPart or Batch (depending on the digital twin type). +- Fetch the submodel SerialPart or Batch (depending on the digital twin type) from the EDC that is referenced in the corresponding Submodel Descriptor. - The submodel then contains the Unique ID of the built-in part in its catenaXId attribute. -These steps have to be repeated for all built-in parts by the manufacturer. After that, the manufacturer has all information to create the AssemblyPartRelationship. +These steps have to be repeated for all built-in parts by the manufacturer. After that, the manufacturer has all information to create the SingleLevelBomAsBuilt. #### Publish Traceability Data Offers at EDC -Currently, only the format and content of the `asset:prop:id` attribute is mandatory. All other attributes can be used optionally by data providers. - -- `asset:prop:id`: This is the EDC asset ID and must have the following format: `-` +With the changes of Release 3.2 regarding the submodel endpoints in the DTR, the actual EDC asset structure for submodels is no longer restricted by use case conventions and can be decided by the data provider. ##### Data Provider Tasks Basically, as a data provider you have to do the following - Implement a Backend Data Service (BDS) for every asset that is provided via the EDC. It does not have to be a different BDS for each asset - you can use the same BDS for several assets (to be verified). -- The BDS must support the AAS Interface Shell REST-API. +- The BDS must support the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification (see [standard CX-0002](https://catena-x.net/de/standard-library) for more details). - The BDS must use the REST API data plan for data transmission. -- The BDS must verify that it only returns data to the data consumer that is compliant for the asset and data offer for which data is queried. As a data offer is always assigned to one data consumer, only data must be returned that is accessible for the data consumer. +- The BDS must verify that it only returns data to the data consumer that is compliant to the EDC asset and data offer for which data is queried and authorize the request accordingly. diff --git a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png index 34ff323a175..d1d02ec1a58 100644 Binary files a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png and b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png differ diff --git a/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png b/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png index a137b9b0026..89cb01b93fb 100644 Binary files a/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png and b/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png differ diff --git a/docs-kits/kits/Traceability Kit/page_adoption-view.md b/docs-kits/kits/Traceability Kit/page_adoption-view.md index 5406c98944c..bdbe5c2fa89 100644 --- a/docs-kits/kits/Traceability Kit/page_adoption-view.md +++ b/docs-kits/kits/Traceability Kit/page_adoption-view.md @@ -23,7 +23,7 @@ The aim of the Traceability KIT is to trace parts and materials across the entir The Traceability KIT provides the necessary standards, aspect models, APIs, logics, and processes on how to build a data sovereign data chain and send quality notifications. This is done via the standardized creation of digital twins of components and vehicles 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. This enables businesses to track and trace products, components, material, and software along the value chain for all product lifecycle stages. -All described specifications in the KIT are based on Catena-X standards like Asset Administration Shell, DAPS and Digital Twin Registry. They refer to other Catena-X KITs like the Connector KIT (EDC), Data Chain KIT (Item Relation Ship, IRS) and Business Partner KIT to ensure interoperability and data sovereignty according to IDSA and Gaia-X principles. +All described specifications in the KIT are based on Catena-X standards like Data Space Connector, Asset Administration Shell (AAS), and Digital Twin Registry (DTR). They refer to other Catena-X KITs like the Connector KIT (EDC), Data Chain KIT (Item Relation Ship, IRS) and Business Partner KIT to ensure interoperability and data sovereignty according to IDSA and Gaia-X principles. Furthermore, APIs and data models enable partners to send quality notifications in a standardized way while already knowing which parts of their direct customer and suppliers are affected and which are not. Moreover, the KIT is compatible with the data chain KIT to allow apps and business to traverse through the data chains over n-tier levels to enable further use cases like Circular Economy. @@ -194,30 +194,31 @@ Defined - Digital Twin Batch - Digital Twin Vehicle - Build up the basic chain - - Aspect model "SerialPartTypization" + - Aspect model "SerialPart" - Aspect model "AssemblyPartRelation" - Aspect model "Batch" - Aspect model "JustInSequencePart" + - Aspect model "TractionBatteryCode" ### AsBuilt Aspect Models -#### 1. SerialPartTypization +#### 1. SerialPart A serialized part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a serial numbers or a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number) -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) -#### 2. AssemblyPartRelationship +#### 2. SingleLevelBomAsBuilt The aspect provides the child parts (one structural level down) which the given object assembles. -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0) #### 3. Batch 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. A batch is identified via a Batch ID. -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) #### 4. JustInSequencePart @@ -225,6 +226,12 @@ A just-in-sequence part is an instantiation of a (design-) part, where the parti Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.just_in_sequence_part/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.just_in_sequence_part/1.0.0) +#### 5. TractionBatteryCode + +The aspect provides the information of the Traction battery code of a battery cell, a battery module or a battery pack according to the chinese standard GB/T 34014-2017. Furthermore, it provides the traction battery codes for the assembled sub parts of the component, e.g. Traction battery code of a battery module plus all the traction battery codes of the assembled battery cells of this battery module. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0) + ## Logic & Schema @@ -238,155 +245,169 @@ This architecture overview only shows Catena-X Core Services that are directly a | Subsystem | Description | |:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Data Provisioning | This component provides a company's data to the Catena-X network by transforming it into the Catena-X format and publishing it. In Catena-X, data must be provided to the network based on existing standards from the other Kits. One example that can be used is the Connector Kit that builds a component based on the IDS protocol, e.g. the Connector of the Eclipse Dataspace Components (EDC). As standard for digital twins, the Asset Administration Shell (AAS) standard is used - this is relevant for registering digital twins (in the Digital Twin Registry) as well as for providing digital twin data. The data format used for Traceability data is based on the BAMM aspects models published in the Semantic Hub. | -| Traceability App | Enables traceability functionalities like quality alerts or notifications. When a Traceability App fetches data for digital twins (submodels), there are two options:
  • Directly access the partner's EDC (and the Digital Twin Registry) to connect to other partner's EDC and retrieve the data from ther
  • Use a local IRS service to get the data and let the IRS handle the EDC and Digital Twin Registry communication.
| +| Data Provisioning | This component provides a company's data to the Catena-X network by transforming it into the Catena-X format and publishing it. In Catena-X, data must be provided to the network based on existing standards from the other Kits. One example that can be used is the Connector Kit that builds a component based on the DSP protocol, e.g. the Connector of the Eclipse Dataspace Components (EDC). As standard for digital twins, the Asset Administration Shell standard is used - this is relevant for registering digital twins (in the Digital Twin Registry) as well as for providing digital twin data. The data format used for Traceability data is based on the BAMM aspects models published in the Semantic Hub. | +| Traceability App | Enables traceability functionalities like quality alerts or notifications. When a Traceability App fetches data for digital twins (submodels), there are two options:
  • Directly access the partner's EDC and DTR to connect to other partner's EDC and retrieve the data from ther
  • Use a local IRS service to get the data and let the IRS handle the EDC and DTR communication.
| | Internal Systems | Existing internal systems of a Catena-X partner which provide data to Traceability components.
  • For Data Provisioning: The data provided to Catena-X via the EDC should be fetched from a partner's internal PLM and parts master data systems.
  • For Traceability Apps: A Traceability App may show more data to a user than just the data that is provided to Catena-X (and fetched via the Data Provisioning component). The business scope of COTS software is bigger than just Traceability and they have existing interfaces to fetch all data they need for their business functionality (and not only Traceability data).
Both components can also send data back to internal systems. That's at the discretion of the Catena-X partner and neither required nor prohibited by the Traceability use case. | #### Catena-X Core Services | Subsystem | Description | |:-----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Digital Twin Registry | The Digital Twin Registry acts as an address book for Digital Twins. Data Providers register their Digital Twins in the Digital Twin Registry. Data consumers query the Digital Twin Registry to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns. [Repository of the Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry). | -| Item Relationship Service (IRS) | The IRS is providing a technical API Endpoint in the Catena-X Network, which builds an item tree representation of given digital twins stored across the industry. Therefore it is a key component for the Network to provide data chains along the value chain in the industry. [Repository of the IRS](https://github.com/eclipse-tractusx/item-relationship-service). | -| Eclipse Dataspace Components (EDC) | The Connector of the Eclipse Dataspace Components provides a framework for sovereign, inter-organizational data exchange. It will implement the International Data Spaces standard (IDS) as well as relevant protocols associated with GAIA-X. The connector is designed in an extensible way in order to support alternative protocols and integrate in various ecosystems. [Repository of the Catena-X specific EDC](https://github.com/eclipse-tractusx/tractusx-edc). | +| Digital Twin Registry | The Digital Twin Registry acts as an address book for Digital Twins. Data Providers register their Digital Twins in their own Digital Twin Registry. Data consumers query the Digital Twin Registries to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns.

[Repository of the Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry). | +| Item Relationship Service (IRS) | The IRS is providing a technical API Endpoint in the Catena-X Network, which builds an item tree representation of given digital twins stored across the industry. Therefore it is a key component for the Network to provide data chains along the value chain in the industry.

[Repository of the IRS](https://github.com/eclipse-tractusx/item-relationship-service). | +| Eclipse Dataspace Components (EDC) | The Connector of the Eclipse Dataspace Components provides a framework for sovereign, inter-organizational data exchange. It will implement the International Data Spaces standard as well as relevant protocols associated with GAIA-X. The connector is designed in an extensible way in order to support alternative protocols and integrate in various ecosystems.

[Repository of the Catena-X specific EDC](https://github.com/eclipse-tractusx/tractusx-edc). | | Discovery Service | The EDC / dataspace discovery interface is a CX network public available endpoint which can get used to retrieve EDC endpoints and the related BPNs, as well as search for endpoints via the BPN. | ## Business Process -To enable data sovereignty, access and usage policies are important to protect the data assets of a data provider in the EDC, described in the following. +To enable data sovereignty, access and usage policies are important to protect the data assets of a data provider in the EDC, described in the following. Further details are described in the [CX - 0018 Sovereign Data Exchange](#standards) standard. ### Access Policies -To decide which company has access to the data assets, access policy should be used. It is maybe possible to skip access policies, but this will made all data assets public available in the Catena-X network and is not recommended. Therefore, every asset should be protected and only be made available for specific companies, identified through their business partner number (BPN). - -In the near future, other access policies will be introduced like a company role and attribute based policy. +To decide which company has access to the data assets, access policy should be used. Note that without protecting data assets with access policies, they become publicly available in the Catena-X network which is not recommended. Therefore, every asset should be protected and only be made available for specific companies, identified through their business partner number (BPN). #### BPN Access Policy -Description: This policy will allow limiting access to a data offer based on a list of specific BPN. This translates to the following functionality: +This policy allows limiting access to a data offer based on a list of specific BPNs. This translates to the following functionality: - The data offer creator will be able to create a policy listing all the BPN that can access the data offer -- This means that only the connectors registered in DAPS with the BPN listed in the policy can see the data offer and accept it (for the creation of data contracts and subsequent data exchange) +- This means that only the connectors registered in the Catena-X network with the BPN listed in the policy can see the data offer and accept it (for the creation of data contracts and subsequent data exchange) -Examples for single and multiple BPN are described on [this page of the EDC](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/business-partner-validation). +Examples including a JSON payload for single and multiple BPN are described on [this page in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/bpn-validation) or in the [Business Partner Validation Extension part of the Connector Kit](../tractusx-edc/edc-extensions/business-partner-validation/). + +### Usage Policies + +To decide which company can use the data asset under specific conditions, usage policies (or contract policies) are used. Therefore, they are more specific than access policies and only used just after access is granted. Currently, the usage policies aren't technically enforced but based on a legal framework (keep this in mind when publishing data assets). + +Policies are defined based on the [W3C ODRL format](https://www.w3.org/TR/odrl-model/). This allows a standardized way of formulating policy payloads. It further allows to stack different constraints with the `odrl:and` operator. Therefore, every data provider can decide on his or her own under which conditions their data assets are shared in the network. It is recommended to restrict the data usage for all traceability aspects. An example of one usage policy containing three different constraints is shown and described in the following: ```json { - "uid": "", - "prohibitions": [], - "obligations": [], - "permissions": [ - { - "edctype": "dataspaceconnector:permission", - "action": { - "type": "USE" - }, - "constraints": [ - { - "edctype": "AtomicConstraint", - "leftExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "BusinessPartnerNumber" - }, - "rightExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "" - }, - "operator": "EQ" + "@context": { + "odrl": http://www.w3.org/ns/odrl/2/ + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "", // Important for the contract definition + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ // All of the following three constraints have to be fullfilled (and, not or) + // First constraint to verify the the Catena-X membership + { + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + // Second constraint to verify if the framework agreement for the traceability use case is accepted + { + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.traceability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + // Third constraint to define the specific purpose, further detailed in the framework agreement + { + "@type": "Constraint", + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" // See list in the framework agreement + } + ] } - ] - } - ] + } + ] + } } ``` -### Usage Policies - -To decide which company can use the data asset under specific conditions, usage policies are used. Therefore, they are more specific than access policies and only used just after access is granted. The `POST` `/api/v1/data/policydefinitions` endpoint is used to create a usage policy in the EDC. Currently, the usage policies aren't technically enforced (keep this in mind when publishing data assets). - -#### Purpose-based Usage Policy +#### Membership Policy -It is recommended to restrict the data usage for all traceability aspects. This can be made with the purpose restricted data usage policy. It contains a String as `value` that defines the purpose of usage. Every participant in the Catena-X network must follow these purposes. +To verify the participants Catena-X membership, the `Membership` verifiable credential can be used. In case of a policy, the data can only be used from verified Catena-X members. The payload is shown in the first constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#1-membership-constraint). -In the following, the purpose value, their detailed description and the aspects for which they are relevant fore are presented. +```json +{ + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" +} +``` -| Purpose Value | Relevant for | Description | -|--------------------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| R2_Traceability | SerialPartTypization 1.1.0 Batch 1.0.2 | The data can only be used for the Catena-X Use Case Traceability. This means that the data can only be consumed in the context of visualization of parts and vehicles and their relations and quality analysis to e.g. select relevant components for further quality analysis or notifications.
For demonstrations based on artificial data, this policy does not apply. | -| R2_Traceability | AssemblyPartRelationship 1.1.1 | The data can only be used for the Catena-X Use Case Traceability. This means that t he data can only be consumed in the context of visualization of parts and vehicles and their relations and quality analysis to e.g. select relevant components for further quality analysis or notifications.
For demonstrations based on artificial data, this policy does not apply.
_"Assumption: only used by own data provider. No usage of other use cases like dismantling, ESS etc."_ | -| R2_QualityAlert | Notification API | This purpose is intended for a Catena-X Use-Case Traceability. This means that t he data exchange via the Quality Alert Notification endpoint can only be exchanged in the context of visualization of quality-relevant issues of parts and vehicles and their relations . The exchanged data can only be used on a "need to know" basis in the context of quality analysis.
For demonstrations based on artificial data, this policy does not apply. | -| R2_QualityInvestigation | Notification API | This purpose is intended for a Catena-X Use-Case Traceability. This means that the data exchange via the Quality Alert Notification endpoint can only be exchanged in the context of visualization of quality-relevant issues of parts and vehicles and their relations. The exchanged data can only be used on a "need to know" basis in the context of quality analysis.
For demonstrations based on artificial data, this policy does not apply. | +#### Framework Agreement Policy -The JSON payload of a purpose-based usage policy looks as follows: +To verify if a participant accepted the framework agreement of a specific use case created by the [Catena-X association](https://catena-x.net/en/about-us/the-association), the `FrameworkAgreement.traceability` verifiable credential can be used for the traceability framework agreement. In case of a policy, the data can only be used from accepted and verified traceability framework agreement members. This is shown in the second constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#35-traceability). ```json { - "uid": "", - "prohibitions": [], - "obligations": [], - "permissions": [ - { - "edctype": "dataspaceconnector:permission", - "action": { - "type": "USE" - }, - "constraints": [ - { - "edctype": "AtomicConstraint", - "leftExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "idsc:PURPOSE" - }, - "rightExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "" - }, - "operator": "EQ" - } - ] - } - ] + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.traceability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" } ``` -### Contract Definitions +#### Purpose-based Policy + +To further restrict the data usage, a purpose-based policy can be used. If, for example, the purpose mentions a quality investigation, this means that the data usage is only allowed for handling and working on the quality investigation. All possible purposes and their meanings are defined in the traceability framework agreement. This allows to create a uniform understanding and a standardized set of payloads in the network by connecting technical strings to legal agreements. -In the EDC, every policy is associated with a contract. The `POST` `/api/v1/data/contractdefinitions` has the following JSON payload to create a contract definition that creates the relationship: +It is highly recommended to only use this purpose-based policy together with the [Framework Agreement Policy](#framework-agreement-policy). Only with both together it can be ensured that the payload of the purpose policy is agreed by the other part and is based on the same set. + +Details about the endpoint and payload can be found in the [Transfer Data sample in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md#2-setup-data-offer) or in the [Connector Kit API documentation of the policy definition API](tractusx-edc/docs/kit/development-view/openAPI/management-api/policy-definition-api/create-policy-definition). ```json { - "id": "", - "accessPolicyId" : "", - "contractPolicyId" : "", - "criteria": [ - { - "operandLeft": "asset:prop:id", - "operator": "=", - "operandRight": "" - } - ] + "@type": "Constraint", + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" } ``` -The properties in this JSON have the following values: +The `` have to be replaced with one purpose string defined in the framework agreement. + +### Contract Definitions + +In the EDC, every policy is associated with a contract. Thus, a contract definition is needed. Details about the endpoint and payload can be found in the [Transfer Data sample in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md#2-setup-data-offer) or in the [Connector Kit API documentation of the contract definition API](../tractusx-edc/docs/kit/development-view/openAPI/management-api/contract-definition-api/edc-contract-definition-api). + +When using an above mentioned [Access Policy](#access-policies), their `id` needs to be included as a value of the `accessPolicyId` key in the contract definition. When using an above mentioned [Usage Policy](#usage-policies), their `id` needs to be included as a value of the `contractPolicyId` key in the contract definition. -- `acccessPolicyId` is the UUID of the basic policy -- `contractPolicyId` is the UUID of the basic policy -- `criteria` is a list of simple expressions to express, which assets are used in this ContractDefinition. +### Verifiable Credentials -In the current implementation of the EDC only the `in` and `= operators are supported. +Verifiable Credentials (VC) are part of the Self-Sovereign Identity (SSI) standard by the W3C. Details about Catena-X specific VCs can be found in the [CX - 0016 Company Attribute Verification](#standards) standard. As mentioned there, it offers a `UseCaseFrameworkConditionCX` type allowing a data provider to check if specific conditions, like a signed use case contract as introduced in the [Purpose-base Usage Policy section](#purpose-based-policy), are agreed. Further technical documentation are presented in the [SSI Docu](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture) repository. ## Standards Our relevant standards can be downloaded from the official [Catena-X Standard Library](https://catena-x.net/de/standard-library): -- [CX - 0019 Aspect Model: Serial Part Typization](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0019_SerialPartTypization_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0020 Aspect Model:Assembly Part Relationship](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0020_AssemblyPartRelationship_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0021 Aspect Model: Batch](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0021__Batch_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0022 Notification Process](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0022_Notification_Process_v_1.1.1.pdf) -- [CX - 0023 Notification API](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0023_Notification_API_v_1.1.1.pdf) +- [CX - 0018 Sovereign Data Exchange](https://catena-x.net/de/standard-library) +- [CX - 0019 Aspect Model: Serial Part](https://catena-x.net/de/standard-library) +- [CX - 0020 Aspect Model: Single Level BoMAsBuilt](https://catena-x.net/de/standard-library) +- [CX - 0021 Aspect Model: Batch](https://catena-x.net/de/standard-library) +- [CX - 0022 Notification Process](https://catena-x.net/de/standard-library) +- [CX - 0023 Notification API](https://catena-x.net/de/standard-library) +- [CX - 0042 Aspect Model: Single Level BomAsPlanned](https://catena-x.net/de/standard-library) +- [CX - 0043 Semantic Model: Part AsPlanned](https://catena-x.net/de/standard-library) +- [CX - 0093 Aspect Model TractionBatteryCode](https://catena-x.net/de/standard-library) +- [CX - 0094 Aspect Model Part Site Information AsPlanned](https://catena-x.net/de/standard-library) diff --git a/docs-kits/kits/Traceability Kit/page_changelog.md b/docs-kits/kits/Traceability Kit/page_changelog.md index fc1a23676af..443fe8010a0 100644 --- a/docs-kits/kits/Traceability Kit/page_changelog.md +++ b/docs-kits/kits/Traceability Kit/page_changelog.md @@ -11,31 +11,70 @@ sidebar_position: 1 All notable changes to this Kit will be documented in this file. +## [2.0.0] - 2023-09-28 + +Compatible for release 23.09 (also known as 3.2). + +### Added + +- **Adoption View:** + - TractionBatteryCode aspect model + - Information about Verifiable Credentials +- **Development View:** + - TractionBatteryCode aspect model + +### Changed + +- **General:** + - Updated all parts of the KIT related to the digital twin registry as the DTR now has a decentralized architecture + - Updated SerialPartTypization 1.1.1 to SerialPart 1.0.1 + - Updated AssemblyPartRelationship 1.1.1 to SingleLevelBomAsBuilt 1.0.0 + - Updated aspect model Batch from version 1.0.2 to 2.0.0 ([Release Notes](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/RELEASE_NOTES.md)) + - Fixed references to deprecated releases +- **Adoption View:** + - Updated description of the policy section (Access Policies, Usage Policies, Contract Definitions) + - Updated relevant standards for release 3.2 +- **Development View:** + - Updated documentation because of the migration to the new standard AAS v3.0 by the DTR + - Updated conventions for submodel descriptors and EDC asset structure to give data provides more flexibility in how to create EDC assets for submodels of digital twins + - Setting the visibility of entries in a digital twin's specifid asset IDs is now mandatory to ensure need-know + - Removed optional customer attributes from example for Batch aspect model + +### Removed + +- **Adoption View:** + - Policy payloads are removed and replaced by specific documentation links + ## [1.0.1] - 2023-04-14 -

Added

+Compatible for release 3.1. -- Adoption View: Traceability tutorial video -- Adoption View: Customer journey +### Added -

Changed

+- **Adoption View:** + - Traceability tutorial video + - Customer journey + +### Changed - ./. -

Removed

+### Removed - ./. ## [1.0.0] - 2023-04-12 -

Added

+Compatible for release 3.1. + +### Added - Initial version of the Kit including adoption, operation and development view + two API specifications (Notification API, Unique ID Push API) -

Changed

+### Changed - ./. -

Removed

+### Removed - ./. diff --git a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/Software Development View/page_software-development-view.md b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/Software Development View/page_software-development-view.md index 74a8f4a47ee..8f866282926 100644 --- a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/Software Development View/page_software-development-view.md +++ b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/Software Development View/page_software-development-view.md @@ -1,7 +1,7 @@ --- id: Specification Traceability Kit title: Specification -description: 'Traceability Kit' +description: "Traceability Kit" sidebar_position: 4 --- @@ -14,6 +14,7 @@ Development View of the Kit. --> + ## API Specifications ### Unique ID Push Notifications @@ -27,6 +28,7 @@ All endpoints as well as the schema of the notification below are described in d [Publish Traceability Data Offers at EDC](#publish-traceability-data-offers-at-edc) + ## Sample Data In the following, example data for submodels are provided. @@ -114,11 +116,11 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se ### As Built Submodels Sample Data -#### Submodel SerialPartTypization +#### Submodel SerialPart -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) -##### Submodel "SerialPartTypization" for a Vehicle +##### Submodel "SerialPart" for a Vehicle ```json { @@ -127,6 +129,10 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se "key": "manufacturerId", "value": "BPNL7588787849VQ" }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, { "key": "partInstanceId", "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" @@ -149,7 +155,7 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -##### Submodel "SerialPartTypization" for a Serialized Part (Non-Vehicle) +##### Submodel "SerialPart" for a Serialized Part (Non-Vehicle) ```json { @@ -182,45 +188,45 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -#### Submodel AssemblyPartRelationship +#### Submodel SingleLevelBomAsBuilt -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0) -##### Submodel "AssemblyPartRelationship" for a Serialized Part +##### Submodel "SingleLevelBomAsBuilt" for a Serialized Part ```json { "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childParts": [ + "childItems": [ { - "lifecycleContext": "AsBuilt", "quantity": { "quantityNumber": 1.0, "measurementUnit": "unit:piece" }, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04" + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" } ] } ``` -##### Submodel "AssemblyPartRelationship" for a Batch +##### Submodel "SingleLevelBomAsBuilt" for a Batch ```json { "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childParts": [ + "childItems": [ { - "lifecycleContext": "AsBuilt", "quantity": { "quantityNumber": 25.0, "measurementUnit": "unit:kilogram" }, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04" + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" } ] } @@ -228,7 +234,7 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se #### Submodel Batch -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) ##### Submodel "Batch" for a Batch of Raw Material @@ -247,10 +253,8 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", "partTypeInformation": { "manufacturerPartId": "123-0.740-3434-A", - "customerPartId": "PRT-12345", "classification": "product", "nameAtManufacturer": "PA66-GF30", - "nameAtCustomer": "Polyamide" } } ``` @@ -294,7 +298,78 @@ Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-se } ``` -> Please note that if a just-in-sequence part is also a serialized part SerialPartTypization should be used instead. +> Please note that if a just-in-sequence part is also a serialized part SerialPart should be used instead. + +#### Submodel TractionBatteryCode + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0) + +##### Submodel "TractionBatteryCode" for a Battery Cell + +```json +{ + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" +} +``` + +##### Submodel "TractionBatteryCode" for a Battery Module + +```json +{ + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382321" + } + ] +} +``` + +##### Submodel "TractionBatteryCode" for a Battery Pack + +```json +{ + "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" + } + ] + } + ] +} +``` ## Reference Implementation @@ -306,29 +381,29 @@ For a reference implementation, take a look at the open-source Trace-X app. More ### Data Provisioning -The following diagram shows a basic data processing flow how a comany's internal data can be transformed into a Traceability-compliant format. It depicts the necessary steps as well as where communication with other services, e.g., Catena-X network services like the Digital TWin Registry, are necessary. Any implementation of this implementation specification can deviate from this basic flow as it's just one way to do it. But it should give a basic idea what the essential steps are. +The following diagram shows a basic data processing flow how a comany's internal data can be transformed into a Traceability-compliant format. It depicts the necessary steps as well as where communication with other services, e.g., Catena-X network services like the Digital Twin Registry, are necessary. Any implementation of this implementation specification can deviate from this basic flow as it's just one way to do it. But it should give a basic idea what the essential steps are. ![Basic Data FLow](../assets/data_provisioning_data_flow.png) #### Register Digital Twins for Traceability -In Traceability, digital twins for different types of parts are registered at the digital twin registry, e. g. serialized parts, batches, JIS parts or catalog parts. +In Traceability, digital twins for different types of parts are registered at a Digital Twin Registry, e. g. serialized parts, batches, JIS parts or catalog parts. Basic information about how to register digital twins in Catana-X are described in the standard [CX-0002 Digital Twins in Catena-X](https://catena-x.net/de/standard-library). > :raised_hand: **Unique ID Push** -Once a digital twin was created, optionally a Unique ID Push notification can be send to the customer of the part of batch to inform them that a new digital twin is available. +> Once a digital twin was created, optionally a Unique ID Push notification can be send to the customer of the part of batch to inform them that a new digital twin is available. The following general conventions apply for all these digital twins: -- identification: The AAS ID must be a UUIDv4 in URN format: `urn:uuid:` -- globalAssetId: The Unique ID of the real-world part for which a digital twin is created. +- id: The AAS ID must be a UUIDv4 in URN format: `urn:uuid:`; +- globalAssetId: the Unique ID of the real-world part for which a digital twin is created. > :warning: The AAS ID is not the same id as the Catena-X Unique ID, although they have the same format (UUID) and therefore look the same. A Unique ID identifies real-world parts, whereas a AAS ID identifies a digital twin of such a part. So, don't use the same value for Unique ID and AAS ID. ##### Property specificAssetIds -For Traceability, we define some specificAssetIds as mandatory. Mandatory specific asset IDs are used to lookup or search for digital twins. This is a required step by a customer of a part to connect the digital twins of their parts with the digital twins of the suppliers' child parts. To a customer, only the information printed on a real-world part is available and can be used for the lookup. Mandatory specific asset IDs ensure that at least this information is available for the digital twin. +For Traceability, we define some specific asset IDs as mandatory. Mandatory specific asset IDs are used to lookup or search for digital twins. This is a required step by a customer of a part to connect the digital twins of their parts with the digital twins of the suppliers' child parts. To a customer, only the information printed on a real-world part is available and can be used for the lookup. Mandatory specific asset IDs ensure that at least this information is available for the digital twin. -The following conventions for specificAssetIds apply to all digital twins: +The following conventions for specific asset IDs apply to all digital twins:
customerPartId Optional The ID of the type/catalog part from the customer.
The main reason why this propertiy is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. If known, it is recommended to always add the customerPartId for easier lookup.
- If a part has multiple customers, e.g., for batches or catalog parts, multiple customerPartIds can be added. BPN-based access control can be applied to customerPartIds to restrict visiblility.
- Each company that shall have access to a specific customerPartId must be provided as externalSubjectId using its BPN.
- Access to customerPartId only for BPNL1234: - -```json -{ - "key": "customerPartId", - "value": "39192", - "externalSubjectId": "BPNL1234" -} -``` - -In case multiple companies shall have access, each company must be provided in a triple consisting of key, value and externalSubjectId. -If no access control shall be applied, externalSubjectId must be omitted (no access control for `customerPartId`): - -```json -{ - "key": "customerPartId", - "value": "39192" -} -``` + 		The ID of the type/catalog part from the customer.
The main reason why this propertiy is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. In case the manufacturer knows the customer and the corresponding CustomerPartID of its part though, it is required to add this information for easier lookup and to enable further processes.
 String
assetLifecyclePhase Optional Optional (for DT As-Built)
Mandatory (for DT As-Planned) 		The lifecycle phase of the asset.
  • For serialized parts, batches, and JIS parts, use the value "AsBuilt".
  • For catalog parts, use the value "AsPlanned".
 Enum
@@ -349,35 +424,14 @@ The following conventions for specificAssetIds apply to all digital twins: - - + @@ -386,55 +440,188 @@ If no access control shall be applied, externalSubjectId must be omitted (no acc **For serialized parts, additionally the following conventions apply:** | Key | Availability | Description | Type | -|:---------------|:-------------|:---------------------------------------------------------------------------------------------|:-------| +| :------------- | :----------- | :------------------------------------------------------------------------------------------- | :----- | | partInstanceId | Mandatory | The serial number of the part from the manufacturer. | String | | van | Optional | **Only for vehicles:** The pseudonymized vehicle identification number (VIN) of the vehicle. | String | **For batches, additionally the following conventions apply:** | Key | Availability | Description | Type | -|:---------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------| +| :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | | batchId | Optional | The number of the batch from the manufacturer. | String | -| partInstanceId | Mandatory | Also the number of the batch from the manufacturer.

For **Release 3.0**, we also use the batch number as partInstanceId. This makes looking up digital twins for serialized parts and batches easier as a data consumer only has to specify the partInstanceId no matter if they are looking up a serialized part or a batch. Otherwise, the data consumer would need to know for what type of digital twin it is looking for or it would have to look for both until a match is found. | String | +| partInstanceId | Mandatory | Also the number of the batch from the manufacturer.

Currently, we also use the batch number as partInstanceId. This makes looking up digital twins for serialized parts and batches easier as a data consumer only has to specify the partInstanceId no matter if they are looking up a serialized part or a batch. Otherwise, the data consumer would need to know for what type of digital twin it is looking for or it would have to look for both until a match is found. | String | **For just-in-sequence (JIS) parts, additionally the following conventions apply:** -| Key | Availability | Description | Type | -|:-------------------|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------| -| parentOrderNumber | Optional | A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. | String | -| jisNumber | Mandatory | A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. | String | -| jisCallDate | Optional | The date of the just-in-sequence call-off as stated on the call-off document itself.
The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm` | Date | -| partInstanceId | Mandatory | A composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (ifavailable). This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts. | String | +| Key | Availability | Description | Type | +| :---------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | +| parentOrderNumber | Optional | A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. | String | +| jisNumber | Mandatory | A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. | String | +| jisCallDate | Optional | The date of the just-in-sequence call-off as stated on the call-off document itself.
The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm` | Date | +| partInstanceId | Mandatory | A composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (ifavailable). This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts. | String | > :raised_hand: **Lookup of Digital Twins** -The lookup for parts can use the customerPartId or the manufacturerPartId. Both, manufacturer and customer must agree upon what part id will be used for the lookup. Otherwise, when the customer would use the customerPartId for the lookup, but the manufacturer would only provide the manufacturerPartId in its digital twins, the lookup would fail every time. **This is decision that a customer must agree upon with each of their suppliers individually.** +> The lookup for parts can use the customerPartId or the manufacturerPartId. Both, manufacturer and customer must agree upon what part id will be used for the lookup. Otherwise, when the customer would use the customerPartId for the lookup, but the manufacturer would only provide the manufacturerPartId in its digital twins, the lookup would fail every time. **This is decision that a customer must agree upon with each of their suppliers individually.** + +##### Authorization: Visbility of Specific Asset IDs in the DTR + +To enforce a strict need-to-know (and prevent data from being exposed to non-authorized parties), the visibility of entries in the attribute `specificAssetIds` must be protected, i.e.,their visibility must be restricted to authorized parties only. For that, the attribute `externalSubjectId` must be used. Detailed information about this can be found in the [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/category/digital-twin-kit). ##### Submodel Descriptors -The following general conventions apply for all submodel descriptors: - -- `identification`: The submodel ID must be a UUIDv4 in URN format: "urn:uuid:<UUIDv4>" -- `idShort`: The name of the aspect model in camel case, e.g. for aspect SerialPartTypization: "serialPartTypization". -- `endpoints`: For access of submodels via EDC and AAS a new interface type EDC-AAS must be defined. - - `interface`: The value must be "EDC" - - `endpointAddress`: The endpoint address must have the following format: `http://provider.controlplane:port//submodel?content=value&extent=WithBLOBValue` - - `provider.controlplane:port`: server and port of the EDC that is providing the submodel - - `EDC Asset ID`: The EDC asset id under which the submodel was registered in the EDC. It must have the following format `-` - - `AAS ID`: The id of the digital twin (identification property in the AAS descriptor) - - `Submodel`: The id of the submodel (identification property in the submodel descriptor) - - `/submodel`: This method from the AAS Shell Interface that is invoked via the EDC. - - `content=value&extent=WithBLOBValue`: This are currently required parameters when requesting payload via the AAS standard from an EDC - - `endpointProtocol`: The value must be `IDS/ECLIPSE DATASPACE CONNECTOR` - - `endpointProtocolVersion`: The value must be `0.0.1-SNAPSHOT` - -> :raised_hand: **AAS Submodel Descriptor Endpoints** -The endpoint (endpointAddress) in the submodel descriptor cannot be used directly to contact the EDC and access the data. The endpoint has to be re-written as it combines EDC and AAS information. The AAS API Wrapper does that automatically when using it, i.e., it fetches the endpoint from the AAS Registry and re-writes it in a way to a Catena-X EDC with an AAS server in the background can process the query. +General conventions for submodel descriptors can be found in the standard [CX-0002 Digital Twins in Catena-X](https://catena-x.net/de/standard-library). This section is based on it and it is recommended to read it first. In this KIT, we extend this standard with some additional conventions. + +Submodel descriptors MUST be compliant to the following additional conventions: + +- `id`: The submodel ID must be a UUIDv4 in URN format: "urn:uuid:<UUIDv4>"; +- `idShort`: the name of the aspect model in camel case, e.g. for aspect SerialPart: "serialPart". + +The actual access information for the EDC is part of the endpoint attribute in the submodel descriptor. + +```json +{ + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/{path}/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } +} +``` + +The following conventions apply for the endpoint: + +- `interface`, `endpointProtocol`, `endpointProtocolVersion`, `subprotocol`, `subprotocolBodyEncoding`, and `securityAttributes` are set as defined in the [CX-0002 standard](https://catena-x.net/de/standard-library). +- `href`: The endpoint address for the logical operation GetSubmodel that is invoked by a data consumer to get the submodel. It must have the following format: + - `edc.data.plane`: Server and port of the EDC data plane that is providing the submodel. + - `{path}`: This `{path}` string is forwarded to the backend data service by the EDC data plane. Together with the EDC asset information (see below) it must contain all information for the backend data service to return the requested submodel. The actual path depends on the type of backend data service that the data provider uses to handle the request. More details follow below. + - `/submodel`: This `/submodel` string is also forwarded to the backend data service. As AAS Profile SSP-003 of the Submodel Service Specification is mandatory for release 3.2, `href` must have the suffix "/submodel" representing the invokation of the GetSubmodel operation. +- `subprotocolBody`: a semicolon-separated list of parameters used to negotiate the required contract agreement. + - `id=123`: The ID of the EDC asset for which a contract negitiation should be intiated. This ID is also called dataset ID as it is stored as `https://www.w3.org/ns/dcat/dataset.@id` in a catalog entry. This ID must be set by the data provider when creating the asset. Do not confuse this EDC asset ID (dataset ID) with other IDs that might be defined additionally for an EDC asset, e.g., `https://w3id.org/edc/v0.0.1/ns/id` (often refered to as `edc:id`). + - `dspEndpoint`: Server and port of the EDC control plane used for contract negotiation. + +> :raised_hand: **Backend Data Service for Submodels** +According to [CX-0002](https://catena-x.net/de/standard-library), the backend data service identified via `href`and the filter criteria in `subprotocolBody` MUST be conformant to the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification and must at least support the logical operation GetSubmodel. In release 3.2, only the logical parameter Content=Value must be supported via path suffix "/submodel/$value". This might change in later releases. + +With this approach, the EDC asset structure must no longer follow the "one EDC asset per submodel" rule (as in Release 3.1 and before), but gives data providers more flexibility how to create EDC assets for their digital twins and submodels based on how they use `{path}`. + +###### Option 1: Same EDC Asset Structure as in Release 3.1 + +Submodels of digital twins are registered in the EDC the same way as for release 3.1: One EDC asset is created for every submodel of a digital twin. + +- `href` must have the following format: `http://edc.data.plane/submodel` +- `subprotocolBody` must have the following format: `id={edcAssetId};dspEndpoint=http://edc.control.plane` +- edcAssetId is the id of the EDC asset for the submodel. It must have the following format "{aasIdentifier}-{submodelIdentifier}" with + - aasIdentifier: the id of the digital twin (id property in the AAS descriptor) + - submodelIdentifier: the id of the submodel (id property in the submodel descriptor) + +Here's an example how such a submodel descriptor could look like: + +```json +"submodelDescriptors": [ + { + "idShort": "serialPart", + "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=urn:uuid:75e98d67-e09e-4388-b2f6-ea0a0a642bfe-urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0;dspEndpoint=http://edc.control.plane/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } + } + ] + } +] +``` + +In this example, the `path` part in the `href` is empty, as the EDC asset referenced in `subprotocolBody` directly points to a service returning the correct submodel (set up correctly with its dataAddress in the data provider's EDC). + +###### Option 2: EDC Asset Structure on Catalog Part Level + + A data provider can link several submodel endpoints to the same EDC asset (referenced by its id). This allows to create only one EDC asset (per aspect model) for a catalog part and link all submodels (of the same aspect model) for serialized parts of the catalog part to the same EDC asset. The data provider would still need to create separate EDC assets per aspect model as in most cases different usage policies are used for aspect models. + +If a data provider no longer creates EDC assets on the level of submodels, the EDC can no longer authorize a request on a submodel-level. For example: If EDC assets are created per catalog part, the EDC can only authorize if the requestor is allowed to see parts of these type in general; if the requestor is allowed to see a actual serialized part, must be authorized by the backend data service executing the request. + +Here's an example how such a submodel descriptor could look like: + +```json +"submodelDescriptors": [ + { + "idShort": "serialPart", + "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://edc.data.plane/urn%3Auuid%3A75e98d67-e09e-4388-b2f6-ea0a0a642bfe-urn%3Auuid%3A7effd7f4-6353-4401-9547-c54b420a22a0/submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=urn:uuid:1475f313-0a83-4e2b-b705-a100eebcb7d7;dspEndpoint=http://control-plane.edc.catena-x.net/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { "type": "NONE", "key": "NONE", "value": "NONE" } + ] + } + } + ] + } +] +``` + +The path part of the `href` property contains the information for the backend data service which digital twin's submodel to return while the EDC asset ID is used for several endpoints. The path part here is just an example as it depends on the type of backend data service the data provider uses. + +The above options are only two examples how a submodel's endpoint can be created. As long as it's compliant with the above conventions (including [CX-0002](https://catena-x.net/de/standard-library)) a data provider can also use any other EDC asset structure. + +###### Data Consumption with AAS Submodel Descriptor Endpoints + +The endpoint `href` in the submodel descriptor cannot be used directly to contact an EDC and access the data in Catena-X. + +- A data consumer must first identify the protocol that must be used to retrieve the submodel data based on the `subprotocol`. For data transfers in Catena-X, this is "DSP" +- With `href`, the data consumer calls the local operation GetSubmodel as specified by the suffix "/submodel". As only the logical parameter "Content" must be supported in release 3.2, "/$value" must be appended to `href` by the data consumer. + If the `href` endpoint is called with operations or parameter values not yet supported, the error response 501 "Not Implemented" must be returned according to [CX-0002](https://catena-x.net/de/standard-library). +- Then, the data consumer must use the information in the `subprotocolBody` to perform a contract negotiation for the EDC asset referenced by `id` with the EDC control plane of the data provider specified by `dspEndpoint`. +- Finally, using the id from the contract agreement with the control plane, the data consumer initiates the data transfer with the EDC data plane of the data provider referenced in the `href`. The enriched path part of the `href` (see bullet point 2) is passed to data provider data plane by the data consumer as a parameter for the backend data service that actually executes the request and returns the submodel. + +All these steps must be handled by the data consumer that want to retrieve the submodel data of a digital twin. #### Lookup for Digital Twins in the Digital Twin Registry For a data provider, there are currently the following steps where they have to lookup digital twins of other partners in the Catena-X network. -- The data provider must use the local IDs for a serialized part or batch (manufacturer, part number, serial or batch number) and for a just-in-sequence part (manufacturer, parentOrderNumber, jisNumber, jisCallDate) to lookup the AAS ID of the digital twin of this serialized part, batch or just-in-sequence part. The AAS descriptor with this ID contains the Unique ID of the serialized part, batch or just-in-sequence (as globalAssetId) that is used to create the AssembyPartRelationship submodel. +- The data provider must use the local IDs for a serialized part or batch (manufacturer, part number, serial or batch number) and for a just-in-sequence part (manufacturer, parentOrderNumber, jisNumber, jisCallDate) to lookup the AAS ID of the digital twin of this serialized part, batch or just-in-sequence part. The AAS descriptor with this ID contains the Unique ID of the serialized part, batch or just-in-sequence (as globalAssetId) that is used to create SingleLevelBomAsBuilt submodel. - The data provider must use the local IDs for a catalog part (manufacturer, part number) to lookup the AAS ID of the digital twin of this catalog part. The AAS descriptor with this ID contains the Unique ID of the catalog part (as globalAssetId) that is used to create the SingleLevelBoMAsPlanned submodel. @@ -445,7 +632,7 @@ For a data consumer, there are currently the following steps where they have to ##### Lookup up a Digital Twin with Local IDs -The local IDs of a serialized part (manufacturer, part number, serial number) are stored as specificAssetIds in the AAS descriptor of the digital twin. From the Digital Twin Registry API, the following function can be used for this lookup `GET /lookup/shells`. +The local IDs of a serialized part (manufacturer, part number, serial number) are stored as specific asset IDs in the AAS descriptor of the digital twin. From the Digital Twin Registry API, the following function can be used for this lookup `GET /lookup/shells`. All Asset identifier key-value-pairs used as parameter to this lookup function are combined using AND. An example query would look like this: `https://URL/registry/lookup/shells?assetIds=%5B%7B%22key%22%3A%20%22manufacturerId%22,%22value%22%3A%20%22BPNL7588787849VQ%22%7D,%7B%22key%22%3A%20%22manufacturerPartId%22,%22value%22%3A%20%2295657362-83%22%7D,%7B%22key%22%3A%20%22partInstanceId%22,%22value%22%3A%20%22NO-574868639429552535768526%22%7D%5D` @@ -470,28 +657,26 @@ All Asset identifier key-value-pairs used as parameter to this lookup function a The lookup (for serialized parts/batches as well as catalog parts) can use the customer or the manufacturer part id (manufacturerPartId or manufacturerPartId). -- For a digital twin, adding the customer part id to the specificAssetId property is optional (see (TRS) Create Digital Twins for Serialized Parts and Batches incl. Submodels). The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the specifiAssetId property for easier lookup (by customers). +- For a digital twin, adding the customer part id to the specific asset IDs is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the specifiAssetId property for easier lookup (by customers). - A customer that wants to do a lookup for a supplier's digital twin, must first decide what id they want to use for the lookup. This depends on the information that is available to them. - If the customer knows the manufacturer part id, they should use the manufacturer part id for the lookup as the manufacturer part id is guaranteed to be available in the digital twin (as the manufacturer part id is a mandatory property). - - If the customer does not know the manufacturer part id, they must use the customer part id (i.e., their own part id). In that case they must make sure that their suppliers register their digital twins with this information (as the customer part id is optional) as part of the specificAssetId property. This is decision that a customer must agree upon with each of their suppliers individually. + - If the customer does not know the manufacturer part id, they must use the customer part id (i.e., their own part id). In that case they must make sure that their suppliers register their digital twins with this information (as the customer part id is optional) as part of the specific asset IDs. This is decision that a customer must agree upon with each of their suppliers individually. As a result, the AAS ID of the digital twin with this local IDs is returned. The AAS ID can then be used to retrieve details about the digital twin, i.e. the digital twin's AAS descriptor including submodel descriptors. **Example result for looking up a digital twin with local IDs:** ```json -[ - "urn:uuid:c227a880-b82b-40f7-846c-3942ddf26c29" -] -```` +["urn:uuid:c227a880-b82b-40f7-846c-3942ddf26c29"] +``` Note that this query can return more than one AAS ID depending on the local IDs uniquely identifying a digital twin or not. -For Release 3.0, even if more than one digital twin is returned in a lookup, these digital twins should have different submodels assigned to them. These submodels should be disjunct and not overlap. This means that you can use the submodel to filter out the correct digital twin. +Currently, even if more than one digital twin is returned in a lookup, these digital twins should have different submodels assigned to them. These submodels should be disjunct and not overlap. This means that you can use the submodel to filter out the correct digital twin. - If there are returned more than one digital twin with the same submodel (based on their semanticId), this is considered an error. Processing should be canceled and an error message should be reported. -The next section describes to to modify the lookup to additionally restrict the results to digital twins with a specific submodel type based on it's semanticId. +The next section describes to modify the lookup to additionally restrict the results to digital twins with a specific submodel type based on it's semanticId. #### Unique ID Push Notifications @@ -511,7 +696,7 @@ Secondly, EDCs are being used for the exchange and it is currently required to o ##### Unique ID Push Process Overview -How the actual process is triggered is application specific. It is recommended to to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication). +How the actual process is triggered is application specific. It is recommended to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication). The Unique ID push is initiated by the supplier (acting as sender) towards their customer (acting as receiver). Since the Unique ID of the asset (i.e., serial unit / batch) is unknown in the logistics process, the message needs to include local identifiers to be matched towards the information from the delivery documents and furthermore the internal data of the recipient's traceability solution. @@ -519,9 +704,7 @@ Upon receipt of the message, the customer needs to match the local identifiers w - If there is an object for incoming deliveries, this event could be updated. Alternatively, if only production events are tracked, the data could be integrated at this point into the data provisioning pipeline's data structure for consumed materials. -- In the end this enables the customer to integrate the child parts into the AssemblyPartRelationship aspect. - -In the end this enables the customer to integrate the child parts into the AssemblyPartRelationship aspect. +- In the end this enables the customer to integrate the child parts into the SingleLevelBomAsBuilt aspect. ![Unique ID Push Process](../assets/unique_id_push_process.png) @@ -542,7 +725,7 @@ participant "BPDM API" as BPM order 4 end box box "Customer Landscape" #lightyellow -participant "EDC Customer" as EDCCust order 5 +participant "EDC Customer" as EDCCust order 5 participant "Data Provisioning Customer" as TraceCust order 6 end box @@ -576,20 +759,20 @@ The notifications send to inform a customer about the creating of a new digital All endpoints as well as the schema of the notification below are described in detail in the [Unique ID Push API documentation](Unique%20ID%20Push%20API/unique-id-push-notification-api). -> Adding the customer part id to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, if they know it, it is recommended to always add the customer part id to the notification. +> Adding the customer part id to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, in case the manufacturer knows the customer and the corresponding customer part id of its part though, it is required to always add the customer part id to the notification. ##### Notification Receiver (Customer) Here is a short overview what the receiver has to do when they want to support Unique Id Push notifications. This is an optional feature. -- The Receiver in this scenario is the customer of a part. -- The Receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured. +- The receiver in this scenario is the customer of a part. +- The receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured. - The EDC in which the notification EDC asset was created must be registered at the Discovery Service (so that the sender can find the partner's EDC which should receive notifications) - When the Receiver receives a Unique Id Push notification, it must process this notification after it was received by the EDC (in a Backend Data Service) - How the Receiver processes the notification is up to them, but the following steps are recommended: - Verify the correctness of the data in the notification (i.e., the receiver is actually the customer of this part). - Store the notification data for later. - - Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to the digital twin registry. + - Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to a supplier's Digital Twin Registry. ###### EDC Asset @@ -615,7 +798,7 @@ In general, a data provider is free to decide which usage policies to define for Keep in mind that usage policies currently aren't technically enforced by the EDC or other components. > :raised_hand: **Usage Policy for Unique ID Push** -The Unique ID push notification endpoints are protected with a purpose-based usage policy and "R3-1_UniqueIDPush" as purpose. +> The Unique ID push notification endpoints are protected with a purpose-based usage policy and "R3-1_UniqueIDPush" as purpose. ###### Backend Data Service to Process Unique ID Push Notifications @@ -637,51 +820,50 @@ There should only be one EDC which provides the notification EDC asset for Uniqu #### Creating Submodels for Digital Twins -Submodels for Traceability are mostly easy to create by transforming a company's internal data into the target aspect model, i.e. SerialPartTypization or Batch. Transformations are mostly straightforward in these cases. +Submodels for Traceability are mostly easy to create by transforming a company's internal data into the target aspect model, i.e. SerialPart or Batch. Transformations are mostly straightforward in these cases. The only special step in creating these two submodels is the initial creation of the Unique ID for the corresponding serialized parts or batches. -##### Creation of Submodel AssemblyPartRelationship +##### Creation of Submodel SingleLevelBomAsBuilt -The creation of the submodel AssemblyPartRelationship is more complicated. This submodel contains the Unique ID of the manufacturer's part (attribute catenaXId) which is created - as described above - when the part's SerialPartTypization or Batch submodel is created. But it also contains the Unique IDs of the built-in parts (attributes childParts.childCatenaXId), as shown in the following example: +The creation of the submodel SingleLevelBomAsBuilt is more complicated. This submodel contains the Unique ID of the manufacturer's part (attribute catenaXId) which is created - as described above - when the part's SerialPart or Batch submodel is created. But it also contains the Unique IDs of the built-in parts (attributes childItems.catenaXId), as shown in the following example: ```json { "catenaXId": "urn:uuid:d261e0fa-36f5-4128-875e-0f5735f5a535", - "childParts": [ + "childItems": [ { "quantity": { "quantityNumber": 1, "measurementUnit": "unit:piece" }, - "lifecycleContext": "AsBuilt", "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:9dc1b6fb-94e7-4911-9e39-abf06c4941d2" + "catenaXId": "urn:uuid:9dc1b6fb-94e7-4911-9e39-abf06c4941d2", + "businessPartner": "SingleLevelBomAsBuilt" }, { "quantity": { "quantityNumber": 1, "measurementUnit": "unit:piece" }, - "lifecycleContext": "AsBuilt", "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:d17bbf68-6cb7-4045-b3ae-67f41403d098" + "catenaXId": "urn:uuid:d17bbf68-6cb7-4045-b3ae-67f41403d098", + "businessPartner": "SingleLevelBomAsBuilt" } ] } - ``` -For the build-in parts (child parts), their Unique ID is not known to the manufacturer initially. Only know are the local ids that are printed on the physical part (serialized part or batch), i.e., manufacturer (BPN), manufacturer part id and serial or batch number. To get the Unique ID of a built-in part, a data provider therefore has to do the follwoing: +For the build-in parts (child items), their Unique ID is not known to the manufacturer initially. Only know are the local ids that are printed on the physical part (serialized part or batch), i.e., manufacturer (BPN), manufacturer part id and serial or batch number. To get the Unique ID of a built-in part, a data provider therefore has to do the following: - Get all necessary local ids for the built-in part: - manufacturer (BPN), manufacturer part id and serial number for serialized parts - manufacturer (BPN), manufacturer part id and batch number for batches - The next step is about getting the Unique ID of all built-in parts. There are two ways: - Unique IDs might for built-in parts might already be available locally if Unique ID Push is supported by the data provider and the suppliers of the built-in parts. - - Query the Digital Twin Registry to find the digital twin for this built-in part + - Query a supplier's Digital Twin Registry to find the digital twin for this built-in part ###### Unique ID Push @@ -689,31 +871,29 @@ Once the digital twin was created, optionally a Unique ID Push notification can For more information, see [Unique ID Push Notifications](#unique-id-push-notifications) -###### Query the Digital Twin Registry to find the digital twin for this built-in part +###### Query a Digital Twin Registry to find the digital twin for this built-in part -- Querying digital twins is described in (TRS) Lookup for Digital Twins at the Digital Twin Registry +- Querying digital twins is described in [Lookup for Digital Twins in the Digital Twin Registry](#lookup-for-digital-twins-in-the-digital-twin-registry) - Note that the query parameters differ depending on what type of digital twin is looked up. - - For Release 3.0 though, no matter if you want to lookup serialized parts or batches, you can use partInstanceId (using the serial number or the batch number as search parameter value). - - For Batch digital twins, the key batchId might be provided optionally. As this key is not mandatory for Release 2, you cannot rely on this key being available when looking for Batch digital twins. - - To understand why, take a look at how these digital twins are created, especially their specificAssetIds: (TRS) Create Digital Twins for Serialized Parts and Batches incl. Submodels + - Currently though, no matter if you want to lookup serialized parts or batches, you can use partInstanceId (using the serial number or the batch number as search parameter value). + - For Batch digital twins, the key batchId might be provided optionally. As this key is not mandatory currently, you cannot rely on this key being available when looking for Batch digital twins. + - To understand why, take a look at how these digital twins are created, especially their specific asset IDs: [Creating Submodels for Digital Twins](#creating-submodels-for-digital-twins) - The result of this query will be the AAS ID of the digital twin. -- Use this AAS ID to get the AAS Descriptor including all Submodel Descriptors of this digital twin. The AAS Descriptor contains the Submodel Descriptor SerialPartTypization or Batch (depending on the digital twin type). -- Fetch the submodel SerialPartTypization or Batch (depending on the digital twin type) from the EDC that is referenced in the corresponding Submodel Descriptor. +- Use this AAS ID to get the AAS Descriptor including all Submodel Descriptors of this digital twin. The AAS Descriptor contains the Submodel Descriptor SerialPart or Batch (depending on the digital twin type). +- Fetch the submodel SerialPart or Batch (depending on the digital twin type) from the EDC that is referenced in the corresponding Submodel Descriptor. - The submodel then contains the Unique ID of the built-in part in its catenaXId attribute. -These steps have to be repeated for all built-in parts by the manufacturer. After that, the manufacturer has all information to create the AssemblyPartRelationship. +These steps have to be repeated for all built-in parts by the manufacturer. After that, the manufacturer has all information to create the SingleLevelBomAsBuilt. #### Publish Traceability Data Offers at EDC -Currently, only the format and content of the `asset:prop:id` attribute is mandatory. All other attributes can be used optionally by data providers. - -- `asset:prop:id`: This is the EDC asset ID and must have the following format: `-` +With the changes of Release 3.2 regarding the submodel endpoints in the DTR, the actual EDC asset structure for submodels is no longer restricted by use case conventions and can be decided by the data provider. ##### Data Provider Tasks Basically, as a data provider you have to do the following - Implement a Backend Data Service (BDS) for every asset that is provided via the EDC. It does not have to be a different BDS for each asset - you can use the same BDS for several assets (to be verified). -- The BDS must support the AAS Interface Shell REST-API. +- The BDS must support the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification (see [standard CX-0002](https://catena-x.net/de/standard-library) for more details). - The BDS must use the REST API data plan for data transmission. -- The BDS must verify that it only returns data to the data consumer that is compliant for the asset and data offer for which data is queried. As a data offer is always assigned to one data consumer, only data must be returned that is accessible for the data consumer. +- The BDS must verify that it only returns data to the data consumer that is compliant to the EDC asset and data offer for which data is queried and authorize the request accordingly. diff --git a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/architecture_level_1.png b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/architecture_level_1.png index 34ff323a175..d1d02ec1a58 100644 Binary files a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/architecture_level_1.png and b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/architecture_level_1.png differ diff --git a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/data_provisioning_data_flow.png b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/data_provisioning_data_flow.png index a137b9b0026..89cb01b93fb 100644 Binary files a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/data_provisioning_data_flow.png and b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/assets/data_provisioning_data_flow.png differ diff --git a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_adoption-view.md b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_adoption-view.md index 5406c98944c..bdbe5c2fa89 100644 --- a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_adoption-view.md +++ b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_adoption-view.md @@ -23,7 +23,7 @@ The aim of the Traceability KIT is to trace parts and materials across the entir The Traceability KIT provides the necessary standards, aspect models, APIs, logics, and processes on how to build a data sovereign data chain and send quality notifications. This is done via the standardized creation of digital twins of components and vehicles 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. This enables businesses to track and trace products, components, material, and software along the value chain for all product lifecycle stages. -All described specifications in the KIT are based on Catena-X standards like Asset Administration Shell, DAPS and Digital Twin Registry. They refer to other Catena-X KITs like the Connector KIT (EDC), Data Chain KIT (Item Relation Ship, IRS) and Business Partner KIT to ensure interoperability and data sovereignty according to IDSA and Gaia-X principles. +All described specifications in the KIT are based on Catena-X standards like Data Space Connector, Asset Administration Shell (AAS), and Digital Twin Registry (DTR). They refer to other Catena-X KITs like the Connector KIT (EDC), Data Chain KIT (Item Relation Ship, IRS) and Business Partner KIT to ensure interoperability and data sovereignty according to IDSA and Gaia-X principles. Furthermore, APIs and data models enable partners to send quality notifications in a standardized way while already knowing which parts of their direct customer and suppliers are affected and which are not. Moreover, the KIT is compatible with the data chain KIT to allow apps and business to traverse through the data chains over n-tier levels to enable further use cases like Circular Economy. @@ -194,30 +194,31 @@ Defined - Digital Twin Batch - Digital Twin Vehicle - Build up the basic chain - - Aspect model "SerialPartTypization" + - Aspect model "SerialPart" - Aspect model "AssemblyPartRelation" - Aspect model "Batch" - Aspect model "JustInSequencePart" + - Aspect model "TractionBatteryCode" ### AsBuilt Aspect Models -#### 1. SerialPartTypization +#### 1. SerialPart A serialized part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a serial numbers or a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number) -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part_typization/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) -#### 2. AssemblyPartRelationship +#### 2. SingleLevelBomAsBuilt The aspect provides the child parts (one structural level down) which the given object assembles. -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.assembly_part_relationship/1.1.1) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/1.0.0) #### 3. Batch 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. A batch is identified via a Batch ID. -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/1.0.2) +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) #### 4. JustInSequencePart @@ -225,6 +226,12 @@ A just-in-sequence part is an instantiation of a (design-) part, where the parti Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.just_in_sequence_part/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.just_in_sequence_part/1.0.0) +#### 5. TractionBatteryCode + +The aspect provides the information of the Traction battery code of a battery cell, a battery module or a battery pack according to the chinese standard GB/T 34014-2017. Furthermore, it provides the traction battery codes for the assembled sub parts of the component, e.g. Traction battery code of a battery module plus all the traction battery codes of the assembled battery cells of this battery module. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.traction_battery_code/1.0.0) + ## Logic & Schema @@ -238,155 +245,169 @@ This architecture overview only shows Catena-X Core Services that are directly a | Subsystem | Description | |:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Data Provisioning | This component provides a company's data to the Catena-X network by transforming it into the Catena-X format and publishing it. In Catena-X, data must be provided to the network based on existing standards from the other Kits. One example that can be used is the Connector Kit that builds a component based on the IDS protocol, e.g. the Connector of the Eclipse Dataspace Components (EDC). As standard for digital twins, the Asset Administration Shell (AAS) standard is used - this is relevant for registering digital twins (in the Digital Twin Registry) as well as for providing digital twin data. The data format used for Traceability data is based on the BAMM aspects models published in the Semantic Hub. | -| Traceability App | Enables traceability functionalities like quality alerts or notifications. When a Traceability App fetches data for digital twins (submodels), there are two options:
  • Directly access the partner's EDC (and the Digital Twin Registry) to connect to other partner's EDC and retrieve the data from ther
  • Use a local IRS service to get the data and let the IRS handle the EDC and Digital Twin Registry communication.
| +| Data Provisioning | This component provides a company's data to the Catena-X network by transforming it into the Catena-X format and publishing it. In Catena-X, data must be provided to the network based on existing standards from the other Kits. One example that can be used is the Connector Kit that builds a component based on the DSP protocol, e.g. the Connector of the Eclipse Dataspace Components (EDC). As standard for digital twins, the Asset Administration Shell standard is used - this is relevant for registering digital twins (in the Digital Twin Registry) as well as for providing digital twin data. The data format used for Traceability data is based on the BAMM aspects models published in the Semantic Hub. | +| Traceability App | Enables traceability functionalities like quality alerts or notifications. When a Traceability App fetches data for digital twins (submodels), there are two options:
  • Directly access the partner's EDC and DTR to connect to other partner's EDC and retrieve the data from ther
  • Use a local IRS service to get the data and let the IRS handle the EDC and DTR communication.
| | Internal Systems | Existing internal systems of a Catena-X partner which provide data to Traceability components.
  • For Data Provisioning: The data provided to Catena-X via the EDC should be fetched from a partner's internal PLM and parts master data systems.
  • For Traceability Apps: A Traceability App may show more data to a user than just the data that is provided to Catena-X (and fetched via the Data Provisioning component). The business scope of COTS software is bigger than just Traceability and they have existing interfaces to fetch all data they need for their business functionality (and not only Traceability data).
Both components can also send data back to internal systems. That's at the discretion of the Catena-X partner and neither required nor prohibited by the Traceability use case. | #### Catena-X Core Services | Subsystem | Description | |:-----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Digital Twin Registry | The Digital Twin Registry acts as an address book for Digital Twins. Data Providers register their Digital Twins in the Digital Twin Registry. Data consumers query the Digital Twin Registry to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns. [Repository of the Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry). | -| Item Relationship Service (IRS) | The IRS is providing a technical API Endpoint in the Catena-X Network, which builds an item tree representation of given digital twins stored across the industry. Therefore it is a key component for the Network to provide data chains along the value chain in the industry. [Repository of the IRS](https://github.com/eclipse-tractusx/item-relationship-service). | -| Eclipse Dataspace Components (EDC) | The Connector of the Eclipse Dataspace Components provides a framework for sovereign, inter-organizational data exchange. It will implement the International Data Spaces standard (IDS) as well as relevant protocols associated with GAIA-X. The connector is designed in an extensible way in order to support alternative protocols and integrate in various ecosystems. [Repository of the Catena-X specific EDC](https://github.com/eclipse-tractusx/tractusx-edc). | +| Digital Twin Registry | The Digital Twin Registry acts as an address book for Digital Twins. Data Providers register their Digital Twins in their own Digital Twin Registry. Data consumers query the Digital Twin Registries to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns.

[Repository of the Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry). | +| Item Relationship Service (IRS) | The IRS is providing a technical API Endpoint in the Catena-X Network, which builds an item tree representation of given digital twins stored across the industry. Therefore it is a key component for the Network to provide data chains along the value chain in the industry.

[Repository of the IRS](https://github.com/eclipse-tractusx/item-relationship-service). | +| Eclipse Dataspace Components (EDC) | The Connector of the Eclipse Dataspace Components provides a framework for sovereign, inter-organizational data exchange. It will implement the International Data Spaces standard as well as relevant protocols associated with GAIA-X. The connector is designed in an extensible way in order to support alternative protocols and integrate in various ecosystems.

[Repository of the Catena-X specific EDC](https://github.com/eclipse-tractusx/tractusx-edc). | | Discovery Service | The EDC / dataspace discovery interface is a CX network public available endpoint which can get used to retrieve EDC endpoints and the related BPNs, as well as search for endpoints via the BPN. | ## Business Process -To enable data sovereignty, access and usage policies are important to protect the data assets of a data provider in the EDC, described in the following. +To enable data sovereignty, access and usage policies are important to protect the data assets of a data provider in the EDC, described in the following. Further details are described in the [CX - 0018 Sovereign Data Exchange](#standards) standard. ### Access Policies -To decide which company has access to the data assets, access policy should be used. It is maybe possible to skip access policies, but this will made all data assets public available in the Catena-X network and is not recommended. Therefore, every asset should be protected and only be made available for specific companies, identified through their business partner number (BPN). - -In the near future, other access policies will be introduced like a company role and attribute based policy. +To decide which company has access to the data assets, access policy should be used. Note that without protecting data assets with access policies, they become publicly available in the Catena-X network which is not recommended. Therefore, every asset should be protected and only be made available for specific companies, identified through their business partner number (BPN). #### BPN Access Policy -Description: This policy will allow limiting access to a data offer based on a list of specific BPN. This translates to the following functionality: +This policy allows limiting access to a data offer based on a list of specific BPNs. This translates to the following functionality: - The data offer creator will be able to create a policy listing all the BPN that can access the data offer -- This means that only the connectors registered in DAPS with the BPN listed in the policy can see the data offer and accept it (for the creation of data contracts and subsequent data exchange) +- This means that only the connectors registered in the Catena-X network with the BPN listed in the policy can see the data offer and accept it (for the creation of data contracts and subsequent data exchange) -Examples for single and multiple BPN are described on [this page of the EDC](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/business-partner-validation). +Examples including a JSON payload for single and multiple BPN are described on [this page in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/bpn-validation) or in the [Business Partner Validation Extension part of the Connector Kit](../tractusx-edc/edc-extensions/business-partner-validation/). + +### Usage Policies + +To decide which company can use the data asset under specific conditions, usage policies (or contract policies) are used. Therefore, they are more specific than access policies and only used just after access is granted. Currently, the usage policies aren't technically enforced but based on a legal framework (keep this in mind when publishing data assets). + +Policies are defined based on the [W3C ODRL format](https://www.w3.org/TR/odrl-model/). This allows a standardized way of formulating policy payloads. It further allows to stack different constraints with the `odrl:and` operator. Therefore, every data provider can decide on his or her own under which conditions their data assets are shared in the network. It is recommended to restrict the data usage for all traceability aspects. An example of one usage policy containing three different constraints is shown and described in the following: ```json { - "uid": "", - "prohibitions": [], - "obligations": [], - "permissions": [ - { - "edctype": "dataspaceconnector:permission", - "action": { - "type": "USE" - }, - "constraints": [ - { - "edctype": "AtomicConstraint", - "leftExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "BusinessPartnerNumber" - }, - "rightExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "" - }, - "operator": "EQ" + "@context": { + "odrl": http://www.w3.org/ns/odrl/2/ + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "", // Important for the contract definition + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ // All of the following three constraints have to be fullfilled (and, not or) + // First constraint to verify the the Catena-X membership + { + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + // Second constraint to verify if the framework agreement for the traceability use case is accepted + { + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.traceability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + // Third constraint to define the specific purpose, further detailed in the framework agreement + { + "@type": "Constraint", + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" // See list in the framework agreement + } + ] } - ] - } - ] + } + ] + } } ``` -### Usage Policies - -To decide which company can use the data asset under specific conditions, usage policies are used. Therefore, they are more specific than access policies and only used just after access is granted. The `POST` `/api/v1/data/policydefinitions` endpoint is used to create a usage policy in the EDC. Currently, the usage policies aren't technically enforced (keep this in mind when publishing data assets). - -#### Purpose-based Usage Policy +#### Membership Policy -It is recommended to restrict the data usage for all traceability aspects. This can be made with the purpose restricted data usage policy. It contains a String as `value` that defines the purpose of usage. Every participant in the Catena-X network must follow these purposes. +To verify the participants Catena-X membership, the `Membership` verifiable credential can be used. In case of a policy, the data can only be used from verified Catena-X members. The payload is shown in the first constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#1-membership-constraint). -In the following, the purpose value, their detailed description and the aspects for which they are relevant fore are presented. +```json +{ + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" +} +``` -| Purpose Value | Relevant for | Description | -|--------------------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| R2_Traceability | SerialPartTypization 1.1.0 Batch 1.0.2 | The data can only be used for the Catena-X Use Case Traceability. This means that the data can only be consumed in the context of visualization of parts and vehicles and their relations and quality analysis to e.g. select relevant components for further quality analysis or notifications.
For demonstrations based on artificial data, this policy does not apply. | -| R2_Traceability | AssemblyPartRelationship 1.1.1 | The data can only be used for the Catena-X Use Case Traceability. This means that t he data can only be consumed in the context of visualization of parts and vehicles and their relations and quality analysis to e.g. select relevant components for further quality analysis or notifications.
For demonstrations based on artificial data, this policy does not apply.
_"Assumption: only used by own data provider. No usage of other use cases like dismantling, ESS etc."_ | -| R2_QualityAlert | Notification API | This purpose is intended for a Catena-X Use-Case Traceability. This means that t he data exchange via the Quality Alert Notification endpoint can only be exchanged in the context of visualization of quality-relevant issues of parts and vehicles and their relations . The exchanged data can only be used on a "need to know" basis in the context of quality analysis.
For demonstrations based on artificial data, this policy does not apply. | -| R2_QualityInvestigation | Notification API | This purpose is intended for a Catena-X Use-Case Traceability. This means that the data exchange via the Quality Alert Notification endpoint can only be exchanged in the context of visualization of quality-relevant issues of parts and vehicles and their relations. The exchanged data can only be used on a "need to know" basis in the context of quality analysis.
For demonstrations based on artificial data, this policy does not apply. | +#### Framework Agreement Policy -The JSON payload of a purpose-based usage policy looks as follows: +To verify if a participant accepted the framework agreement of a specific use case created by the [Catena-X association](https://catena-x.net/en/about-us/the-association), the `FrameworkAgreement.traceability` verifiable credential can be used for the traceability framework agreement. In case of a policy, the data can only be used from accepted and verified traceability framework agreement members. This is shown in the second constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#35-traceability). ```json { - "uid": "", - "prohibitions": [], - "obligations": [], - "permissions": [ - { - "edctype": "dataspaceconnector:permission", - "action": { - "type": "USE" - }, - "constraints": [ - { - "edctype": "AtomicConstraint", - "leftExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "idsc:PURPOSE" - }, - "rightExpression": { - "edctype": "dataspaceconnector:literalexpression", - "value": "" - }, - "operator": "EQ" - } - ] - } - ] + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.traceability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" } ``` -### Contract Definitions +#### Purpose-based Policy + +To further restrict the data usage, a purpose-based policy can be used. If, for example, the purpose mentions a quality investigation, this means that the data usage is only allowed for handling and working on the quality investigation. All possible purposes and their meanings are defined in the traceability framework agreement. This allows to create a uniform understanding and a standardized set of payloads in the network by connecting technical strings to legal agreements. -In the EDC, every policy is associated with a contract. The `POST` `/api/v1/data/contractdefinitions` has the following JSON payload to create a contract definition that creates the relationship: +It is highly recommended to only use this purpose-based policy together with the [Framework Agreement Policy](#framework-agreement-policy). Only with both together it can be ensured that the payload of the purpose policy is agreed by the other part and is based on the same set. + +Details about the endpoint and payload can be found in the [Transfer Data sample in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md#2-setup-data-offer) or in the [Connector Kit API documentation of the policy definition API](tractusx-edc/docs/kit/development-view/openAPI/management-api/policy-definition-api/create-policy-definition). ```json { - "id": "", - "accessPolicyId" : "", - "contractPolicyId" : "", - "criteria": [ - { - "operandLeft": "asset:prop:id", - "operator": "=", - "operandRight": "" - } - ] + "@type": "Constraint", + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" } ``` -The properties in this JSON have the following values: +The `` have to be replaced with one purpose string defined in the framework agreement. + +### Contract Definitions + +In the EDC, every policy is associated with a contract. Thus, a contract definition is needed. Details about the endpoint and payload can be found in the [Transfer Data sample in the tractus-x EDC repository](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md#2-setup-data-offer) or in the [Connector Kit API documentation of the contract definition API](../tractusx-edc/docs/kit/development-view/openAPI/management-api/contract-definition-api/edc-contract-definition-api). + +When using an above mentioned [Access Policy](#access-policies), their `id` needs to be included as a value of the `accessPolicyId` key in the contract definition. When using an above mentioned [Usage Policy](#usage-policies), their `id` needs to be included as a value of the `contractPolicyId` key in the contract definition. -- `acccessPolicyId` is the UUID of the basic policy -- `contractPolicyId` is the UUID of the basic policy -- `criteria` is a list of simple expressions to express, which assets are used in this ContractDefinition. +### Verifiable Credentials -In the current implementation of the EDC only the `in` and `= operators are supported. +Verifiable Credentials (VC) are part of the Self-Sovereign Identity (SSI) standard by the W3C. Details about Catena-X specific VCs can be found in the [CX - 0016 Company Attribute Verification](#standards) standard. As mentioned there, it offers a `UseCaseFrameworkConditionCX` type allowing a data provider to check if specific conditions, like a signed use case contract as introduced in the [Purpose-base Usage Policy section](#purpose-based-policy), are agreed. Further technical documentation are presented in the [SSI Docu](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture) repository. ## Standards Our relevant standards can be downloaded from the official [Catena-X Standard Library](https://catena-x.net/de/standard-library): -- [CX - 0019 Aspect Model: Serial Part Typization](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0019_SerialPartTypization_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0020 Aspect Model:Assembly Part Relationship](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0020_AssemblyPartRelationship_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0021 Aspect Model: Batch](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0021__Batch_UseCaseTraceability_v_1.0.1.pdf) -- [CX - 0022 Notification Process](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0022_Notification_Process_v_1.1.1.pdf) -- [CX - 0023 Notification API](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0023_Notification_API_v_1.1.1.pdf) +- [CX - 0018 Sovereign Data Exchange](https://catena-x.net/de/standard-library) +- [CX - 0019 Aspect Model: Serial Part](https://catena-x.net/de/standard-library) +- [CX - 0020 Aspect Model: Single Level BoMAsBuilt](https://catena-x.net/de/standard-library) +- [CX - 0021 Aspect Model: Batch](https://catena-x.net/de/standard-library) +- [CX - 0022 Notification Process](https://catena-x.net/de/standard-library) +- [CX - 0023 Notification API](https://catena-x.net/de/standard-library) +- [CX - 0042 Aspect Model: Single Level BomAsPlanned](https://catena-x.net/de/standard-library) +- [CX - 0043 Semantic Model: Part AsPlanned](https://catena-x.net/de/standard-library) +- [CX - 0093 Aspect Model TractionBatteryCode](https://catena-x.net/de/standard-library) +- [CX - 0094 Aspect Model Part Site Information AsPlanned](https://catena-x.net/de/standard-library) diff --git a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_changelog.md b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_changelog.md index fc1a23676af..443fe8010a0 100644 --- a/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_changelog.md +++ b/docs-kits_versioned_docs/version-23.09/kits/Traceability Kit/page_changelog.md @@ -11,31 +11,70 @@ sidebar_position: 1 All notable changes to this Kit will be documented in this file. +## [2.0.0] - 2023-09-28 + +Compatible for release 23.09 (also known as 3.2). + +### Added + +- **Adoption View:** + - TractionBatteryCode aspect model + - Information about Verifiable Credentials +- **Development View:** + - TractionBatteryCode aspect model + +### Changed + +- **General:** + - Updated all parts of the KIT related to the digital twin registry as the DTR now has a decentralized architecture + - Updated SerialPartTypization 1.1.1 to SerialPart 1.0.1 + - Updated AssemblyPartRelationship 1.1.1 to SingleLevelBomAsBuilt 1.0.0 + - Updated aspect model Batch from version 1.0.2 to 2.0.0 ([Release Notes](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/RELEASE_NOTES.md)) + - Fixed references to deprecated releases +- **Adoption View:** + - Updated description of the policy section (Access Policies, Usage Policies, Contract Definitions) + - Updated relevant standards for release 3.2 +- **Development View:** + - Updated documentation because of the migration to the new standard AAS v3.0 by the DTR + - Updated conventions for submodel descriptors and EDC asset structure to give data provides more flexibility in how to create EDC assets for submodels of digital twins + - Setting the visibility of entries in a digital twin's specifid asset IDs is now mandatory to ensure need-know + - Removed optional customer attributes from example for Batch aspect model + +### Removed + +- **Adoption View:** + - Policy payloads are removed and replaced by specific documentation links + ## [1.0.1] - 2023-04-14 -

Added

+Compatible for release 3.1. -- Adoption View: Traceability tutorial video -- Adoption View: Customer journey +### Added -

Changed

+- **Adoption View:** + - Traceability tutorial video + - Customer journey + +### Changed - ./. -

Removed

+### Removed - ./. ## [1.0.0] - 2023-04-12 -

Added

+Compatible for release 3.1. + +### Added - Initial version of the Kit including adoption, operation and development view + two API specifications (Notification API, Unique ID Push API) -

Changed

+### Changed - ./. -

Removed

+### Removed - ./.
customerPartId Optional The ID of the type/catalog part from the customer.
The main reason why this propertiy is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. If known, it is recommended to always add the customerPartId for easier lookup.
- If a part has multiple customers, e.g., for batches or catalog parts, multiple customerPartIds can be added. BPN-based access control can be applied to customerPartIds to restrict visiblility.
- Each company that shall have access to a specific customerPartId must be provided as externalSubjectId using its BPN.
- Access to customerPartId only for BPNL1234: - -```json -{ - "key": "customerPartId", - "value": "39192", - "externalSubjectId": "BPNL1234" -} -``` - -In case multiple companies shall have access, each company must be provided in a triple consisting of key, value and externalSubjectId. -If no access control shall be applied, externalSubjectId must be omitted (no access control for `customerPartId`): - -```json -{ - "key": "customerPartId", - "value": "39192" -} -``` + 		The ID of the type/catalog part from the customer.
The main reason why this propertiy is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. In case the manufacturer knows the customer and the corresponding CustomerPartID of its part though, it is required to add this information for easier lookup and to enable further processes.
 String
assetLifecyclePhase Optional Optional (for DT As-Built)
Mandatory (for DT As-Planned) 		The lifecycle phase of the asset.
  • For serialized parts, batches, and JIS parts, use the value "AsBuilt".
  • For catalog parts, use the value "AsPlanned".
 Enum