diff --git a/docs-kits/kits/Traceability Kit/Software Development View/page_app-provider_software-development-view.mdx b/docs-kits/kits/Traceability Kit/Software Development View/page_app-provider_software-development-view.mdx new file mode 100644 index 00000000000..c7c17bb4039 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/Software Development View/page_app-provider_software-development-view.mdx @@ -0,0 +1,38 @@ +--- +id: App Provider Development View Traceability Kit +title: App Provider +description: "Traceability Kit" +sidebar_position: 2 +--- + + + +import AspectModels from './part_aspect-models.mdx' +import Policies from './part_policies.mdx' +import Notice from '../part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + +The following page offers specific developer resources, including payloads and API endpoints for data consumer and app provider. It is important to read the business and architecture view first to understand everything. + + + + + + \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/Software Development View/page_data-provider_software-development-view.mdx b/docs-kits/kits/Traceability Kit/Software Development View/page_data-provider_software-development-view.mdx new file mode 100644 index 00000000000..43417132d92 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/Software Development View/page_data-provider_software-development-view.mdx @@ -0,0 +1,46 @@ +--- +id: Data Provider Development View Traceability Kit +title: Data Provider +description: "Traceability Kit" +sidebar_position: 1 +--- + + + +import BillOfMaterials from './part_bill-of-materials.mdx' +import AspectModels from './part_aspect-models.mdx' +import DigitalTwin from './part_digital-twin.mdx' +import Policies from './part_policies.mdx' +import Notice from '../part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + +The following page offers specific developer resources, including payloads and API endpoints for data providers. It is important to read the business and architecture view first to understand everything. + + + + + + + + + + + + diff --git a/docs-kits/kits/Traceability Kit/Software Development View/part_aspect-models.mdx b/docs-kits/kits/Traceability Kit/Software Development View/part_aspect-models.mdx new file mode 100644 index 00000000000..85fef047e5f --- /dev/null +++ b/docs-kits/kits/Traceability Kit/Software Development View/part_aspect-models.mdx @@ -0,0 +1,434 @@ +--- +sidebar_class_name: hidden +--- + + + +## Aspect Models + +### AsPlanned + +#### Short Introduction: What is a BoM AsPlanned? + +The BoM AsPlanned is the generic list of all possible catalogue parts & materials for a specific vehical project and the supply chain from OEM to raw material suppliers. The BoM is also called 120% which means that it includes alternative parts / materials (e.g. LED headlights and XENON headlights) and parts for certain markets. It will be set up way before Start of Production (SOP) and be updated if the contents are updated. It is used for Sourcing / Production Planning and always reflects the current state of parts / materials build into this specific vehicle project. + +The BoM AsPlanned also includes all versions of parts like changed parts. It has to enable parts/materials provided from multiple manufacturers or the same manufacturer at different production sites. Additionally it must be possible to map relations of the same part/material to different customers. + +The complexity of generic is much higher than BoM AsBuilt. It is used for technical topics, e.g., Supply Chain Act, DCM. + +#### Definition Status of the BoM AsPlanned + +Defined + +- Digital Twins + - Digtial Twin "PartType" + +- Traceability data aspect models + - Aspect model "PartAsPlanned" + - Aspect model "SingleLevelBoMAsPlanned" + - Aspect model "SingelLevelUsageAsPlanned" + - Aspect model "PartSiteInformationAsPlanned" + +#### 1. PartAsPlanned + +A Part as Planned represents an item in the Catena-X Bill of Material (BOM) in As-Planned lifecycle status in a specific version. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1) + +##### Example: Submodel `PartAsPlanned` for a Catalog Part + +```json +{ + "partTypeInformation": { + "classification": "component", + "manufacturerPartId": "123-0.740-3434-A", + "nameAtManufacturer": "Mirror left" + }, + "validityPeriod": { + "validFrom": "2021-06-14T06:55:29.935Z", + "validTo": "2022-06-14T06:55:29.935Z" + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379" +} +``` + +#### 2. SingelLevelBomAsPlanned + +The single-level Bill of Material represents one sub-level of an assembly and does not include any lower-level subassemblies. In as planned lifecycle state all variants are covered (\"120% BoM\"). If multiple versions of child parts exist that can be assembled into the same parent part, all versions of the child part are included in the BoM. If there are multiple suppliers for the same child part, each supplier has an entry for their child part in the BoM. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_planned/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_planned/2.0.0) + +##### Example: Submodel `SingleLevelBomAsPlanned` for a Catalog Part + +```json +{ + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "childItems": [ + { + "catenaXId": "urn:uuid:5daB938E-Cafa-92B3-7ca1-9aD7885e9dC8" + "quantity": { + "quantityNumber": 2.5, + "measurementUnit": "unit:litre" + }, + "createdOn": "2022-02-03T14:48:54.709Z", + "businessPartner": "BPNL50096894aNXY", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + ] +} +``` + +#### 3. SingelLevelUsageAsPlanned + +The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0) + +##### Example: Submodel `SingleLevelUsageAsPlanned` for a Catalog Part + +```json +{ + "parentParts": [ + { + "parentCatenaXId": "urn:uuid:c8B01D5A-ce0B-6Dd4-5bA0-A3e3fcE9cA93", + "quantity": { + "quantityNumber": 2.5, + "measurementUnit": "unit:litre" + }, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d" +} +``` + +#### 4. PartSiteInformationAsPlanned + +The aspect provides site related information for a given as planned item (i.e. a part type or part instance that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the \"as planned\" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part (type) is planned. + +Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0) + +##### Example: Submodel `PartSiteInformationAsPlanned` for a Component that is Produced at the Given Site + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "sites": [ + { + "catenaXSiteId": "BPNS1234567890ZZ", + "functionValidUntil": "2025-11-21T11:14:30.825+01:00", + "function": "production", + "functionValidFrom": "2022-11-21T11:14:30.825+01:00" + } + ] +} +``` + +### AsBuilt + +#### Short Introduction: What is a BoM AsBuilt? + +A BoM AsBuilt resembles a single vehicle, which means that each vehicle built has its own individual BoM asBuilt. The BoM includes all part/components which either have a serial number, batch number, JIS number (sequence number) or a combination out of these. This means, that there is a direct and specific connection between a parent and a child part/component so that an accurate and exact traceability is possible. + +Also, the BoM is called 100%, as there are no alternative parts included but only built parts. Therefore, it will be set up when a part is produced and can be connected to its parent and child parts. + +In Catena-X the BoM asBuilt is used for technical topics, e.g., Quality, Battery Passport (CE). + +#### Definition Status of the BoM AsBuilt + +Defined + +- Digital Twins + - Digital Twin Serialized Part + - Digital Twin Batch + - Digital Twin Vehicle +- Build up the basic chain + - Aspect model "SerialPart" + - Aspect model "AssemblyPartRelation" + - Aspect model "Batch" + - Aspect model "JustInSequencePart" + - Aspect model "TractionBatteryCode" + +#### 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/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) + +##### Example: Submodel `SerialPart` for a Vehicle + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, + { + "key": "partInstanceId", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + }, + { + "key": "van", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU" + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "manufacturerPartID": "QX-39", + "classification": "product", + "nameAtManufacturer": "Vehicle Model A" + } +} +``` + +##### Example: Submodel `SerialPart` for a Serialized Part (Non-Vehicle) + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, + { + "key": "partInstanceId", + "value": "NO-574868639429552535768526" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU" + }, + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "partTypeInformation": { + "manufacturerPartID": "95657362-83", + "customerPartId": "798-515297795-A", + "classification": "component", + "nameAtManufacturer": "High Voltage Battery", + "nameAtCustomer": "High Voltage Battery" + } +} +``` + +#### 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.single_level_bom_as_built/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built/2.0.0) + +##### Example: Submodel `SingleLevelBomAsBuilt` for a Serialized Part + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "childItems": [ + { + "quantity": { + "quantityNumber": 1.0, + "measurementUnit": "unit:piece" + }, + "hasAlternatives": false, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z", + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" + } + ] +} +``` + +##### Submodel `SingleLevelBomAsBuilt` for a Batch + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "childItems": [ + { + "quantity": { + "quantityNumber": 25.0, + "measurementUnit": "unit:kilogram" + }, + "hasAlternatives": false, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z", + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "businessPartner": "BPNL50096894aNXY" + } + ] +} +``` + +#### 3. 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/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) + +##### Example: Submodel `Batch` for a Batch of Raw Material + +```json +{ + "localIdentifiers": [ + { + "value": "BID12345678", + "key": "batchId" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "HUR" + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "manufacturerPartId": "123-0.740-3434-A", + "classification": "product", + "nameAtManufacturer": "PA66-GF30", + } +} +``` + +#### 4. JustInSequencePart + +A just-in-sequence part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a combination of several IDs related to a just-in-sequence process. + +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) + +##### Example: Submodel `JustInSequencePart` for a non-serialized component + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "jisNumber", + "value": "894651684" + }, + { + "key": "parentOrderNumber", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + }, + { + "key": "jisCallDate", + "value": "2022-01-24T09:13:34" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU" + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "manufacturerPartID": "84816168424", + "classification": "product", + "nameAtManufacturer": "Black Leather Front Row Seat for Vehicle Model B" + } +} +``` + +> Please note that if a just-in-sequence part is also a serialized part, SerialPart should be used instead. + +#### 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) + +##### Example: Submodel `TractionBatteryCode` for a Battery Cell + +```json +{ + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" +} +``` + +##### Example: Submodel `TractionBatteryCode` for a Battery Module + +```json +{ + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382321" + } + ] +} +``` + +##### Example: 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" + } + ] + } + ] +} +``` + diff --git a/docs-kits/kits/Traceability Kit/Software Development View/part_bill-of-materials.mdx b/docs-kits/kits/Traceability Kit/Software Development View/part_bill-of-materials.mdx new file mode 100644 index 00000000000..255dd3403d1 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/Software Development View/part_bill-of-materials.mdx @@ -0,0 +1,60 @@ +--- +sidebar_class_name: hidden +--- + + + +## Bill of Material (BoM) + +A bill of material resembles the structure of an end product. It is a list of all raw materials, sub-assemblies and sub-components that are needed to manufacture the end procuct. +At Catena-X Traceability we consider more than one single BoM. The BoM changes during the lifecyle and therefore, we are talking about different BoMs in different lifecycles. + +### BoM Representations + +#### Single-Level BOM + +A single-level BOM represents one level of an assembly and does not include any lower-level subassemblies. + +#### Multi-Level BOM + +A Multi-Level Bill of Materials (BOM) is a [bill of materials (BOM)](https://www.bterrell.com/sage-accpac-erp/manufacturing/definition-multi-level-bom/definition-bom/) that lists the components, assemblies, and materials required to make a part. It provides a display of all components that are directly or indirectly used in a parent item. When an item is a subcomponent, blend, intermediate, etc., all of its components, including purchased parts and [raw materials](https://www.bterrell.com/sage-accpac-erp/manufacturing/definition-multi-level-bom/definition-bom/definition-raw-materials/), are also exhibited. A multilevel structure can be illustrated by a tree with several levels. A multi-level BOM is created by connecting a series of individual single level BOMs together. + +#### Flattened BOM + +Flattening BOM means the intermediate levels in the BOM are removed and the lowest level is directly connected to the highest level. + +### BoM Lifecycle Stages + +BoM LifeCycleStage concept based on STEP AP242 with slight adoptions in layout & wording: + +- Each instance can be identified by unique (within the organization) serial number (SN). +- The ‘multi-SN’ (multi Serial number) describes product defined with a generic part or item +- The ‘one per SN’ (one per Serial number) describes product defined with an individual part or item + +| Name |Identifier Step |Implemented CX |Identifier CX| Description |Purpose |Creating time of BoM | BoM Ausprägungen | one/more fix suppliers | +| :--- | :----:|:----: |:----: |:----: | :----: |:----: |:----: |:----: | +| **AsDesigned (AsDeveloped)** | multi-SN | Currently Not Implemented |Part number*
may not be the specific part number but a code that describes a part
(technische Produktbeschreibung) |BoM asDesigned is generated in the design phase of a new product including alternative parts. |Build up the initial BoM in design phase of a new automotive product including alternative parts
Expected to have research & development part descriptions instead of specific part numbers |starting 2 years before SoP (for e.g. of a new vehicle project) |150% incl. variants which will not be used later |partly known
can be open at this point of time | +| **AsPlanned** | multi-SN | **Implemented** |Part number|BoM AsPlanned is used to plan the manufacturing process including alternative parts. |BoM AsPlanned is used to plan manufacturing including alternative parts.
Sourcing will most likely be based on this (besides key parts which start earlier) |starting 1,5 years before building the first component |120% of all variants are covered, incl. possibly multiple suppliers for the same component |fixed suppliers, could be more than one supplier per part| +| **AsOrdered** | one per SN | Currently Not Implemented |Part number | BoM AsOrdered is used for manufacturing realization. | BoM that is used for manufacturing realization.
This is the list of parts & components currently used for manufactoring after start of production (SOP) or shortly before.| fixed order
(production order or custom order)|100% exact order is known |fixed suppliers, could be more than one supplier per part| +| **AsBuilt** | one per SN | **Implemented**|Serial number / batch number | BoM AsBuilt describes a product as manufactured. | BoM as a component is built or manufactured.
During manufactoring of for e.g. a vehicle the serial numbers & batch numbers are documented (German: Verbaudokumentation).
This leads to one BoM per built car|during building process or directly after finishing|100% |one specific supplier| +| **AsSupported / AsFlying / AsMaintained / AsOperated** | one per SN | Currently Not Implemented |Serial number / batch number | BoM AsMaintained describes the product after purchasing by a customer and updates by maintenance. | BoM after for e.g. a vehicle was picked up by the customer. Changes to live cycle before may apply due to maintenance or repair work e.g. exchange of parts, liquids, ...|Starts when customer has picked up the product, updating if any change is done|100% inkl. replaced parts, incl. history of exchanged parts |one specific supplier| +| **AsRecycled** | - |Currently Not Implemented| Serial number / batch number | BoM AsRecycled describes the BoM after the recycling of the product. | Requirement for Batteries.||100% || + +Two of the considered BoMs are already implemented in the use case Traceability and will be described as follows. + 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/part_digital-twin.mdx similarity index 73% rename from docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md rename to docs-kits/kits/Traceability Kit/Software Development View/part_digital-twin.mdx index 8f866282926..f4feaebafda 100644 --- a/docs-kits/kits/Traceability Kit/Software Development View/page_software-development-view.md +++ b/docs-kits/kits/Traceability Kit/Software Development View/part_digital-twin.mdx @@ -1,391 +1,28 @@ --- -id: Specification Traceability Kit -title: Specification -description: "Traceability Kit" -sidebar_position: 4 +sidebar_class_name: hidden --- -![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + - - - - -## API Specifications - -### Unique ID Push Notifications - -Unique ID Push notifications are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available. The solution is based on notification assets in the EDC (which is the same approach that is used for quality alerts & investigations). The customer creates a notification asset in the EDC and the customer's suppliers send their notifications (with the Unique Id) to this notification asset. Details can be found in section [Unique ID Push Notifications](#unique-id-push-notifications-1). - -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). - -### Traceability Data Offers at EDC - -[Publish Traceability Data Offers at EDC](#publish-traceability-data-offers-at-edc) - - - -## Sample Data - -In the following, example data for submodels are provided. - -### As Planned Submodels Sample Data - -#### Submodel "PartAsPlanned" for a Catalog Part - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1) - -```json -{ - "partTypeInformation": { - "classification": "component", - "manufacturerPartId": "123-0.740-3434-A", - "nameAtManufacturer": "Mirror left" - }, - "validityPeriod": { - "validFrom": "2021-06-14T06:55:29.935Z", - "validTo": "2022-06-14T06:55:29.935Z" - }, - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379" -} -``` - -#### Submodel "SingleLevelBomAsPlanned" for a Catalog Part - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_planned/1.1.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_planned/1.1.0) +## Digital Twin -```json -{ - "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", - "childParts": [ - { - "quantity": { - "quantityNumber": 2.5, - "measurementUnit": "unit:litre" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "childCatenaXId": "urn:uuid:5daB938E-Cafa-92B3-7ca1-9aD7885e9dC8" - } - ] -} -``` - -#### Submodel SingleLevelUsageAsPlanned for a Catalog Part - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0) - -```json -{ - "parentParts": [ - { - "parentCatenaXId": "urn:uuid:c8B01D5A-ce0B-6Dd4-5bA0-A3e3fcE9cA93", - "quantity": { - "quantityNumber": 2.5, - "measurementUnit": "unit:litre" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z" - } - ], - "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d" -} -``` - -#### Submodel "PartSiteInformationAsPlanned" for a component that is produced at the given site - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0) - -```json -{ - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "sites": [ - { - "catenaXSiteId": "BPNS1234567890ZZ", - "functionValidUntil": "2025-11-21T11:14:30.825+01:00", - "function": "production", - "functionValidFrom": "2022-11-21T11:14:30.825+01:00" - } - ] -} -``` - -### As Built Submodels Sample Data - -#### Submodel SerialPart - -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 "SerialPart" for a Vehicle - -```json -{ - "localIdentifiers": [ - { - "key": "manufacturerId", - "value": "BPNL7588787849VQ" - }, - { - "key": "manufacturerPartId", - "value": "95657362-83" - }, - { - "key": "partInstanceId", - "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" - }, - { - "key": "van", - "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" - } - ], - "manufacturingInformation": { - "date": "2022-02-04T14:48:54", - "country": "DEU" - }, - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "partTypeInformation": { - "manufacturerPartID": "QX-39", - "classification": "product", - "nameAtManufacturer": "Vehicle Model A" - } -} -``` - -##### Submodel "SerialPart" for a Serialized Part (Non-Vehicle) - -```json -{ - "localIdentifiers": [ - { - "key": "manufacturerId", - "value": "BPNL7588787849VQ" - }, - { - "key": "manufacturerPartId", - "value": "95657362-83" - }, - { - "key": "partInstanceId", - "value": "NO-574868639429552535768526" - } - ], - "manufacturingInformation": { - "date": "2022-02-04T14:48:54", - "country": "DEU" - }, - "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", - "partTypeInformation": { - "manufacturerPartID": "95657362-83", - "customerPartId": "798-515297795-A", - "classification": "component", - "nameAtManufacturer": "High Voltage Battery", - "nameAtCustomer": "High Voltage Battery" - } -} -``` - -#### Submodel SingleLevelBomAsBuilt - -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 "SingleLevelBomAsBuilt" for a Serialized Part - -```json -{ - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childItems": [ - { - "quantity": { - "quantityNumber": 1.0, - "measurementUnit": "unit:piece" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", - "businessPartner": "BPNL50096894aNXY" - } - ] -} -``` - -##### Submodel "SingleLevelBomAsBuilt" for a Batch - -```json -{ - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "childItems": [ - { - "quantity": { - "quantityNumber": 25.0, - "measurementUnit": "unit:kilogram" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z", - "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", - "businessPartner": "BPNL50096894aNXY" - } - ] -} -``` - -#### Submodel Batch - -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 - -```json -{ - "localIdentifiers": [ - { - "value": "BID12345678", - "key": "batchId" - } - ], - "manufacturingInformation": { - "date": "2022-02-04T14:48:54", - "country": "HUR" - }, - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "partTypeInformation": { - "manufacturerPartId": "123-0.740-3434-A", - "classification": "product", - "nameAtManufacturer": "PA66-GF30", - } -} -``` - -#### Submodel JustInSequencePart - -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) - -##### Submodel "JustInSequencePart" for a non-serialized component - -```json -{ - "localIdentifiers": [ - { - "key": "manufacturerId", - "value": "BPNL7588787849VQ" - }, - { - "key": "jisNumber", - "value": "894651684" - }, - { - "key": "parentOrderNumber", - "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" - }, - { - "key": "jisCallDate", - "value": "2022-01-24T09:13:34" - } - ], - "manufacturingInformation": { - "date": "2022-02-04T14:48:54", - "country": "DEU" - }, - "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", - "partTypeInformation": { - "manufacturerPartID": "84816168424", - "classification": "product", - "nameAtManufacturer": "Black Leather Front Row Seat for Vehicle Model B" - } -} -``` - -> 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 - -For a reference implementation, take a look at the open-source Trace-X app. More information are provided in the [Operation View](../page_software-operation-view.md) section. - - -## Documentation in the Context of Development - -### 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. - -![Basic Data FLow](../assets/data_provisioning_data_flow.png) - -#### Register Digital Twins for Traceability +### Register Digital Twins 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). @@ -432,7 +69,11 @@ The following conventions for specific asset IDs apply to all digital twins: assetLifecyclePhase 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".
+ + The lifecycle phase of the asset: +
  • For serialized parts, batches, and JIS parts, use the value "AsBuilt".
  • For catalog parts, use the value "AsPlanned".
+ assetLifecyclePhase was added to allow data consumers to search only for catalog parts by using assetLifecyclePhase="AsPlanned" as filter. Without this filter, a search for a particular manufacturer part ID would not only return the digital twin of the catalog part, but also all digital twins of instances of this catalog part, i.e., of the corresponding serial parts. + Enum @@ -497,7 +138,7 @@ The actual access information for the EDC is part of the endpoint attribute in t 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). +- `interface`, `endpointProtocol`, `endpointProtocolVersion`, `subprotocol`, `subprotocolBodyEncoding`, and `securityAttributes` are set as defined in the CX-0002 standard. - `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. @@ -507,7 +148,7 @@ The following conventions apply for the endpoint: - `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. +According to CX-0002, 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 Catena-X 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}`. @@ -561,8 +202,8 @@ In this example, the `path` part in the `href` is empty, as the EDC asset refere ###### 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. - +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: @@ -603,7 +244,7 @@ Here's an example how such a submodel descriptor could look like: 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. +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) a data provider can also use any other EDC asset structure. ###### Data Consumption with AAS Submodel Descriptor Endpoints @@ -611,13 +252,13 @@ The endpoint `href` in the submodel descriptor cannot be used directly to contac - 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). + 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. - 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 +### Lookup 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. @@ -678,7 +319,7 @@ Currently, even if more than one digital twin is returned in a lookup, these dig 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 +### Unique ID Push Notifications Unique ID Push notifications are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available. @@ -779,10 +420,10 @@ Here is a short overview what the receiver has to do when they want to support U The EDC asset can be created using the EDC Data Management API. The following conventions apply for the properties of this asset: ```apacheconf -"asset:prop:id": "uniqueidpushnnotification-receipt" -"asset:prop:type": "notification.trace.uniqueidpush" -"asset:prop:notificationtype": "uniqueidpush" -"asset:prop:notificationmethod": "receive" +"id": "uniqueidpushnnotification-receipt" +"type": "notification.trace.uniqueidpush" +"notificationtype": "uniqueidpush" +"notificationmethod": "receive" ``` ###### EDC Policies @@ -798,7 +439,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 "purpose.trace.v1.aspects" as purpose. ###### Backend Data Service to Process Unique ID Push Notifications @@ -818,7 +459,7 @@ The sender must first find the EDC of the customer to which the notification sho There should only be one EDC which provides the notification EDC asset for Unique Id Push. If more than one EDC (for the same BPN/partner) are found, this is considered a misconfiguration of the corresponding partner. -#### Creating Submodels for Digital Twins +### Creating Submodels 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. @@ -837,20 +478,22 @@ The creation of the submodel SingleLevelBomAsBuilt is more complicated. This sub "quantityNumber": 1, "measurementUnit": "unit:piece" }, + "hasAlternatives": false, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", "catenaXId": "urn:uuid:9dc1b6fb-94e7-4911-9e39-abf06c4941d2", - "businessPartner": "SingleLevelBomAsBuilt" + "businessPartner": "BPNL50096894aNXY" }, { "quantity": { "quantityNumber": 1, "measurementUnit": "unit:piece" }, + "hasAlternatives": false, "createdOn": "2022-02-03T14:48:54.709Z", "lastModifiedOn": "2022-02-03T14:48:54.709Z", "catenaXId": "urn:uuid:d17bbf68-6cb7-4045-b3ae-67f41403d098", - "businessPartner": "SingleLevelBomAsBuilt" + "businessPartner": "BPNL50097894aNXA" } ] } @@ -894,6 +537,7 @@ With the changes of Release 3.2 regarding the submodel endpoints in the DTR, the 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 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 support the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification (see standard CX-0002 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 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/Software Development View/part_policies.mdx b/docs-kits/kits/Traceability Kit/Software Development View/part_policies.mdx new file mode 100644 index 00000000000..1b86a508b69 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/Software Development View/part_policies.mdx @@ -0,0 +1,155 @@ +--- +sidebar_class_name: hidden +--- + + + +## Policies + +### Access Policies +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. + +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 + +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 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 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/business-partner-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 +{ + "@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 + } + ] + } + } + ] + } +} +``` +#### Membership Policy + +To verify the participants Catena-X membership, the `Membership` verifiable credential can be used. In case of a policy, the data can only be used from verified Catena-X members. The payload is shown in the first constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#1-membership-constraint). + +```json +{ + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" +} +``` + +#### Framework Agreement Policy + +To verify if a participant accepted the framework agreement of a specific use case created by the [Catena-X association](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 +{ + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.traceability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" +} +``` + +#### Purpose-based Policy + +To further restrict the data usage, a purpose-based policy can be used. If, for example, the purpose mentions a quality investigation, this means that the data usage is only allowed for handling and working on the quality investigation. All possible purposes and their meanings are defined in the traceability framework agreement. This allows to create a uniform understanding and a standardized set of payloads in the network by connecting technical strings to legal agreements. + +It is highly recommended to only use this purpose-based policy together with the [Framework Agreement Policy](#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 +{ + "@type": "Constraint", + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" +} +``` + +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. + +### Verifiable Credentials + +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. diff --git a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license new file mode 100644 index 00000000000..725b4f88d99 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license @@ -0,0 +1,15 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 BASF SE +- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML) +- SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG +- SPDX-FileCopyrightText: 2023 Mercedes Benz AG +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 Siemens AG +- SPDX-FileCopyrightText: 2023 T-Systems International GmbH +- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version) \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png.license b/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png.license new file mode 100644 index 00000000000..725b4f88d99 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/data_provisioning_data_flow.png.license @@ -0,0 +1,15 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 BASF SE +- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML) +- SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG +- SPDX-FileCopyrightText: 2023 Mercedes Benz AG +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 Siemens AG +- SPDX-FileCopyrightText: 2023 T-Systems International GmbH +- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version) \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/traceability_customer-journey.png.license b/docs-kits/kits/Traceability Kit/assets/traceability_customer-journey.png.license new file mode 100644 index 00000000000..725b4f88d99 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/traceability_customer-journey.png.license @@ -0,0 +1,15 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 BASF SE +- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML) +- SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG +- SPDX-FileCopyrightText: 2023 Mercedes Benz AG +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 Siemens AG +- SPDX-FileCopyrightText: 2023 T-Systems International GmbH +- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version) \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/unique_id_push_process.png.license b/docs-kits/kits/Traceability Kit/assets/unique_id_push_process.png.license new file mode 100644 index 00000000000..725b4f88d99 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/unique_id_push_process.png.license @@ -0,0 +1,15 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 BASF SE +- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML) +- SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG +- SPDX-FileCopyrightText: 2023 Mercedes Benz AG +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 Siemens AG +- SPDX-FileCopyrightText: 2023 T-Systems International GmbH +- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version) \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/page_adoption-view.md b/docs-kits/kits/Traceability Kit/page_adoption-view.md deleted file mode 100644 index bdbe5c2fa89..00000000000 --- a/docs-kits/kits/Traceability Kit/page_adoption-view.md +++ /dev/null @@ -1,413 +0,0 @@ ---- -id: Adoption View Traceability Kit -title: Adoption View -description: 'Traceability Kit' -sidebar_position: 2 ---- - -![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) - -### Traceability KIT - - - -## Vision & Mission - -### Vision - -The aim of the Traceability KIT is to trace parts and materials across the entire value chain to enable data driven use cases over all n-tier levels without compromising data sovereignty. This KIT enables data and app providers to deliver solutions for building data chains and to send quality notifications on all levels and industries. - -### Mission - -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 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. - -In the current version, the KIT supports the creation of data chains for the life cycle contexts “as built” and “as planned”. Further lifecycle contexts, e.g., as maintained will be supported in the future. Overall, the KIT represents the backbone to build data chains for use cases based on vehicles and parts. It empowers app providers to develop a Catena-X Traceability application and data provider to implement their digital twins and the connection to their subcomponents themselves. - -### Customer Journey - -With the Traceability KIT, we support the Catena-X customer journey for our adopters and solutions providers. - -![Customer Journey](assets/traceability_customer-journey.png) - - -## Business Value - -Through the standardized specifications described in the “Traceability-KIT” – for example the semantic models and APIs – application and service providers can reduce investment and implementation costs to integrate new Catena-X services. Furthermore, application and service providers can enter potential new markets within the PLM & Quality domain. Data Provider and Businesses are able to build data sovereign data chains to enable data driven use – also for other domains like sustainability. - - -## Use Case - -### Status Quo / Today’s challenge - -From Traceability's perspective, the main challenge within the automotive industry is to define and implement inter-organizational end-to-end data chains across the whole automotive supply chain to empower data driven use cases. Details regarding the challenges are: - -- Missing standards to trace serialized and non-serialized hardware and software components. This includes the datatype, data format and data description (semantics) as well as the data exchange. The existing regulatory requirements that every company within the industry faces today are being solved with individual, proprietary solutions. - -- The digital maturity is diverging within the automotive industry. For bigger companies it is a challenge to receive overall structured data from multiple different suppliers on a broad scale. Smaller companies struggle to generate and provide those data in a fully digitized way. - -- Current solutions are either costly due to expensive distributed ledgers or cannot guarantee trust and data sovereignty based on the GAIA-X and IDSA principles including the regulation of access and usage policies regarding data chains. Therefore, no end-to-end data exchange and cooperation has been achieved as of today. - -### Benefits - -#### OEM and large automotive suppliers - -For OEM and large automotive suppliers: The Traceability solution from Catena-X enables companies to identify products affected by a defect faster and more precisely and thus avoiding general and inaccurate recalls. Through this targeted containment, companies can save both time and money with fewer actions for their customers. Moreover, the Traceability solution enables businesses to rapidly identify the affected part and the corresponding supplier after receiving an alert from the customer. This leads to faster and, therefore, cheaper problem-solving for all parties and less complicated claim management. Furthermore, suppliers can prove compliance of their supply chain to upcoming regulations such as the Supply Chain Act. - -#### SME - -The developed and simple-to-use Traceability solutions support SMEs in their mission to digitize the shop floor and communication with customers and suppliers. Today, in order to provide data to their customers and suppliers, SMEs are obligated to use several, proprietary B2B-interfaces from their customers. With Catena-X aiming to have only one digital interface for all customers and suppliers, it increases the ease of data exchange and saves IT resources. Furthermore, due to the Catena-X data sovereignty principles, all participants know what happens with their data. This increases trust in the data exchange. - -#### Solution Provider - -Solution providers have the potential to scale customer groups and access new market potentials via marketplace and shared service network. - -### Example - Industry Problem - -The KIT enables business to start Quality Investigations and send Quality Alerts in a standardized way while already knowing which parts of your direct customer and suppliers are affected and which are not. - -Through the introduction of unique Catena-X IDs, companies can register digital twins for vehicles, products, components, and raw materials and uniquely identify them within the whole Catena-X ecosystem. Building on that, it is possible to interconnect the registered digital twins of different companies to create a coherent automotive data chain from end-to-end. Furthermore, those twins can easily be complemented with further data like material information to enable further use cases like Circular Economy. - - -## Tutorials - -The following video gives an overview of the presented Traceability Use Case. - - - - - - - -## Semantic Models - -### Bill of Material (BoM) - -A bill of material resembles the structure of an end product. It is a list of all raw materials, sub-assemblies and sub-components that are needed to manufacture the end procuct. -At Catena-X Traceability we consider more than one single BoM. The BoM changes during the lifecyle and therefore, we are talking about different BoMs in different lifecycles. - -#### BoM Representations - -##### Single-Level BOM - -A single-level BOM represents one level of an assembly and does not include any lower-level subassemblies. - -##### Multi-Level BOM - -A Multi-Level Bill of Materials (BOM) is a [bill of materials (BOM)](https://www.bterrell.com/sage-accpac-erp/manufacturing/definition-multi-level-bom/definition-bom/) that lists the components, assemblies, and materials required to make a part. It provides a display of all components that are directly or indirectly used in a parent item. When an item is a subcomponent, blend, intermediate, etc., all of its components, including purchased parts and [raw materials](https://www.bterrell.com/sage-accpac-erp/manufacturing/definition-multi-level-bom/definition-bom/definition-raw-materials/), are also exhibited. A multilevel structure can be illustrated by a tree with several levels. A multi-level BOM is created by connecting a series of individual single level BOMs together. - -##### Flattened BOM - -Flattening BOM means the intermediate levels in the BOM are removed and the lowest level is directly connected to the highest level. - -#### BoM Lifecycle Stages - -BoM LifeCycleStage concept based on STEP AP242 with slight adoptions in layout & wording: - -- Each instance can be identified by unique (within the organization) serial number (SN). -- The ‘multi-SN’ (multi Serial number) describes product defined with a generic part or item -- The ‘one per SN’ (one per Serial number) describes product defined with an individual part or item - -| Name |Identifier Step |Implemented CX |Identifier CX| Description |Purpose |Creating time of BoM | BoM Ausprägungen | one/more fix suppliers | -| :--- | :----:|:----: |:----: |:----: | :----: |:----: |:----: |:----: | -| **AsDesigned (AsDeveloped)** | multi-SN | Currently Not Implemented |Part number*
may not be the specific part number but a code that describes a part
(technische Produktbeschreibung) |BoM asDesigned is generated in the design phase of a new product including alternative parts. |Build up the initial BoM in design phase of a new automotive product including alternative parts
Expected to have research & development part descriptions instead of specific part numbers |starting 2 years before SoP (for e.g. of a new vehicle project) |150% incl. variants which will not be used later |partly known
can be open at this point of time | -| **AsPlanned** | multi-SN | **Implemented** |Part number|BoM AsPlanned is used to plan the manufacturing process including alternative parts. |BoM AsPlanned is used to plan manufacturing including alternative parts.
Sourcing will most likely be based on this (besides key parts which start earlier) |starting 1,5 years before building the first component |120% of all variants are covered, incl. possibly multiple suppliers for the same component |fixed suppliers, could be more than one supplier per part| -| **AsOrdered** | one per SN | Currently Not Implemented |Part number | BoM AsOrdered is used for manufacturing realization. | BoM that is used for manufacturing realization.
This is the list of parts & components currently used for manufactoring after start of production (SOP) or shortly before.| fixed order
(production order or custom order)|100% exact order is known |fixed suppliers, could be more than one supplier per part| -| **AsBuilt** | one per SN | **Implemented**|Serial number / batch number | BoM AsBuilt describes a product as manufactured. | BoM as a component is built or manufactured.
During manufactoring of for e.g. a vehicle the serial numbers & batch numbers are documented (German: Verbaudokumentation).
This leads to one BoM per built car|during building process or directly after finishing|100% |one specific supplier| -| **AsSupported / AsFlying / AsMaintained / AsOperated** | one per SN | Currently Not Implemented |Serial number / batch number | BoM AsMaintained describes the product after purchasing by a customer and updates by maintenance. | BoM after for e.g. a vehicle was picked up by the customer. Changes to live cycle before may apply due to maintenance or repair work e.g. exchange of parts, liquids, ...|Starts when customer has picked up the product, updating if any change is done|100% inkl. replaced parts, incl. history of exchanged parts |one specific supplier| -| **AsRecycled** | - |Currently Not Implemented| Serial number / batch number | BoM AsRecycled describes the BoM after the recycling of the product. | Requirement for Batteries.||100% || - -Two of the considered BoMs are already implemented in the use case Traceability and will be described as follows. - -### Overview "AsPlanned" - -#### Short introduction: what is a BoM AsPlanned? - -The BoM AsPlanned is the generic list of all possible catalogue parts & materials for a specific vehical project and the supply chain from OEM to raw material suppliers. The BoM is also called 120% which means that it includes alternative parts / materials (e.g. LED headlights and XENON headlights) and parts for certain markets. It will be set up way before Start of Production (SOP) and be updated if the contents are updated. It is used for Sourcing / Production Planning and always reflects the current state of parts / materials build into this specific vehicle project. - -The BoM AsPlanned also includes all versions of parts like changed parts. It has to enable parts/materials provided from multiple manufacturers or the same manufacturer at different production sites. Additionally it must be possible to map relations of the same part/material to different customers. - -The complexity of generic is much higher than BoM AsBuilt. It is used for technical topics, e.g., Supply Chain Act, DCM. - -#### Definition Status of the BoM AsPlanned - -Defined - -- Digital Twins - - Digtial Twin "PartType" - -- Traceability data aspect models - - Aspect model "PartAsPlanned" - - Aspect model "SingleLevelBoMAsPlanned" - - Aspect model "SingelLevelUsageAsPlanned" - - Aspect model "PartSiteInformationAsPlanned" - -### AsPlanned Aspect Models - -#### 1. PartAsPlanned - -A Part as Planned represents an item in the Catena-X Bill of Material (BOM) in As-Planned lifecycle status in a specific version. - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_planned/1.0.1) - -#### 2. SingelLevelBomAsPlanned - -The single-level Bill of Material represents one sub-level of an assembly and does not include any lower-level subassemblies. In as planned lifecycle state all variants are covered (\"120% BoM\"). If multiple versions of child parts exist that can be assembled into the same parent part, all versions of the child part are included in the BoM. If there are multiple suppliers for the same child part, each supplier has an entry for their child part in the BoM. - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_planned/1.1.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_planned/1.1.0) - -#### 3. SingelLevelUsageAsPlanned - -The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list. - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_usage_as_planned/1.1.0) - -#### 4. PartSiteInformationAsPlanned - -The aspect provides site related information for a given as planned item (i.e. a part type or part instance that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the \"as planned\" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part (type) is planned. - -Github Link to semantic data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_site_information_as_planned/1.0.0) - -### Overview "AsBuilt" - -#### Short introduction: what is a BoM AsBuilt? - -A BoM AsBuilt resembles a single vehicle, which means that each vehicle built has its own individual BoM asBuilt. The BoM includes all part/components which either have a serial number, batch number, JIS number (sequence number) or a combination out of these. This means, that there is a direct and specific connection between a parent and a child part/component so that an accurate and exact traceability is possible. - -Also, the BoM is called 100%, as there are no alternative parts included but only built parts. Therefore, it will be set up when a part is produced and can be connected to its parent and child parts. - -In Catena-X the BoM asBuilt is used for technical topics, e.g., Quality, Battery Passport (CE). - -#### Definition Status of the BoM AsBuilt - -Defined - -- Digital Twins - - Digital Twin Serialized Part - - Digital Twin Batch - - Digital Twin Vehicle -- Build up the basic chain - - Aspect model "SerialPart" - - Aspect model "AssemblyPartRelation" - - Aspect model "Batch" - - Aspect model "JustInSequencePart" - - Aspect model "TractionBatteryCode" - -### AsBuilt Aspect Models - -#### 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/1.0.1](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part/1.0.1) - -#### 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.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/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.batch/2.0.0) - -#### 4. JustInSequencePart - -A just-in-sequence part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a combination of several IDs related to a just-in-sequence process. - -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 - -### Building Block Architecture Overview - -This architecture overview only shows Catena-X Core Services that are directly accessed by Traceability components, e.g. the EDC is shown, but not the DAPS which is accessed by the EDC, but not directly by the Data Provisioning component. - -![Architecture - Level 1](assets/architecture_level_1.png) - -#### Traceability Components - -| 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 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 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. 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. 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 - -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 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 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 -{ - "@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 - } - ] - } - } - ] - } -} -``` - -#### Membership Policy - -To verify the participants Catena-X membership, the `Membership` verifiable credential can be used. In case of a policy, the data can only be used from verified Catena-X members. The payload is shown in the first constraint-part of the example above and described in detail in the [EDC part of the SSI documentation](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#1-membership-constraint). - -```json -{ - "@type": "Constraint", - "odrl:leftOperand": "Membership", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" -} -``` - -#### Framework Agreement Policy - -To verify if a participant accepted the framework agreement of a specific use case created by the [Catena-X association](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 -{ - "@type": "Constraint", - "odrl:leftOperand": "FrameworkAgreement.traceability", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" -} -``` - -#### Purpose-based Policy - -To further restrict the data usage, a purpose-based policy can be used. If, for example, the purpose mentions a quality investigation, this means that the data usage is only allowed for handling and working on the quality investigation. All possible purposes and their meanings are defined in the traceability framework agreement. This allows to create a uniform understanding and a standardized set of payloads in the network by connecting technical strings to legal agreements. - -It is highly recommended to only use this purpose-based policy together with the [Framework Agreement Policy](#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 -{ - "@type": "Constraint", - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "" -} -``` - -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. - -### Verifiable Credentials - -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 - 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_architecture-view.mdx b/docs-kits/kits/Traceability Kit/page_architecture-view.mdx new file mode 100644 index 00000000000..89961943182 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/page_architecture-view.mdx @@ -0,0 +1,98 @@ +--- +id: Architecture View Traceability Kit +title: Architecture View +description: 'Traceability Kit' +sidebar_position: 2 +--- + + + +import Notice from './part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + + +The following page offers an architecture perspective including the main building blocks and information regarding communication between different components, shown as sequence diagrams in a runtime view. + +In general, data must be provided to the Catena-X network using the Data Space Protocol (DSP). 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. SAMM is used as modelling language to describe the data of digital twins as aspects models. + +## Assumptions +This architecture is based on the following assumptions: + +- The **customers of parts** (on catalog and instance level) must be known when creating a digital twin and registering its data. Registering data in EDC and DTR requires data providers to define appropriate access permissions to prevent exposing data to unauthorized parties. For Traceability, the customer of a part must have access to the digital twin in the DTR as well as to the digital twin's data in the EDC.If the customer is not known when a digital twin is created, additional processes must be set up by the data provider to add access permissions for the customer at a later time. + +## Non-Functional Requirements + +| Requirement | Description | +| :--: |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Resilience | While processing data for publishing it to Catena-X, a data provider needs to access the digital twins of built-in parts from suppliers. These must be available in Catena-X at this point. If these digital twins are not found while the data provider is looking them up, the data provider will not be able to integrate these built-in parts into BoM aspect models (e.g., SingleLevelBomAsBuilt) as it is missing the built-in parts' Unique ID. Reasons for not finding a built-in part's digital twin can be:
  1. There is a network failure while the data provider's is looking for the digital twin.
  2. The supplier did not yet create the digital twin, e.g., because its internal processes were delayed.
  3. The supplier is not yet part of the Catena-X network.
Resilience means that the data provider implements a pipeline that can cope with these issues. Digital twins are provided with the information that is available and are updated once more information is available (e.g., the supplier provides digital twins for built-in parts later on). | + + + + + + + +## Building Block View + +This architecture overview only shows Catena-X Core Services that are directly accessed by Traceability components, e.g. the EDC is shown, but not the DAPS which is accessed by the EDC, but not directly by the Data Provisioning component. + +![Architecture - Level 1](assets/architecture_level_1.png) + +### Traceability Components + +| 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 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 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. | + +## Runtime View + +_Detail runtime views including specific sequence diagrams will follow in the near future._ + + +## Standards + +Our relevant standards can be downloaded from the official [Catena-X Standard Library](https://catena-x.net/de/standard-library): + +- [CX - 0018 Sovereign Data Exchange](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0018-EclipseDataConnector_EDC_-v.2.0.1.pdf) +- [CX - 0019 Aspect Model: Serial Part](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0019-AspectModelSerialPart-v2.0.0.pdf) +- [CX - 0020 Aspect Model: Single Level BoMAsBuilt](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0020-AspectModelSingleLevelBoMAsBuilt-v.2.0.0.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_September23/CX-0023-NotificationAPI-v1.2.2.pdf) +- [CX - 0042 Aspect Model: Single Level BomAsPlanned](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0042-AspectModelSingleLevelBomAsPlanned-v1.1.2.pdf) +- [CX - 0043 Semantic Model: PartAsPlanned](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/PLM_Quality_Use_Case_Traceability/CX_-_0043_Semantic_Model_PartAsPlanned_v_1.0.1.pdf) +- [CX - 0093 Aspect Model Traction Battery Code](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0093-AspectModelTractionBatteryCode-v1.0.0.pdf) +- [CX - 0094 Aspect Model PartSiteInformationAsPlanned](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0094-AspectModelPartSiteInformationAsPlanned-v1.0.0.pdf) + + + diff --git a/docs-kits/kits/Traceability Kit/page_business_view.mdx b/docs-kits/kits/Traceability Kit/page_business_view.mdx new file mode 100644 index 00000000000..f307e1d5bba --- /dev/null +++ b/docs-kits/kits/Traceability Kit/page_business_view.mdx @@ -0,0 +1,106 @@ +--- +id: Business View Traceability Kit +title: Business View +description: 'Traceability Kit' +sidebar_position: 1 +--- + + + +import Notice from './part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + + +The following page offers a high level business view on the Traceability KIT with its vision, mission, benefits, business value, customer journey and examples in form of videos. + + +## Vision & Mission + +### Vision + +The aim of the Traceability KIT is to trace parts and materials across the entire value chain to enable data driven use cases over all n-tier levels without compromising data sovereignty. This KIT enables data and app providers to deliver solutions for building data chains and to send quality notifications on all levels and industries. + +### Mission + +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 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. + +In the current version, the KIT supports the creation of data chains for the life cycle contexts “as built” and “as planned”. Further lifecycle contexts, e.g., as maintained will be supported in the future. Overall, the KIT represents the backbone to build data chains for use cases based on vehicles and parts. It empowers app providers to develop a Catena-X Traceability application and data provider to implement their digital twins and the connection to their subcomponents themselves. + + + +## Business Value & Benefits +### Business Value +Through the standardized specifications described in the “Traceability-KIT” – for example the semantic models and APIs – application and service providers can reduce investment and implementation costs to integrate new Catena-X services. Furthermore, application and service providers can enter potential new markets within the PLM & Quality domain. Data Provider and Businesses are able to build data sovereign data chains to enable data driven use – also for other domains like sustainability. + +### Todays Challenge +From Traceability's perspective, the main challenge within the automotive industry is to define and implement inter-organizational end-to-end data chains across the whole automotive supply chain to empower data driven use cases. Details regarding the challenges are: + +- Missing standards to trace serialized and non-serialized hardware and software components. This includes the datatype, data format and data description (semantics) as well as the data exchange. The existing regulatory requirements that every company within the industry faces today are being solved with individual, proprietary solutions. + +- The digital maturity is diverging within the automotive industry. For bigger companies it is a challenge to receive overall structured data from multiple different suppliers on a broad scale. Smaller companies struggle to generate and provide those data in a fully digitized way. + +- Current solutions are either costly due to expensive distributed ledgers or cannot guarantee trust and data sovereignty based on the GAIA-X and IDSA principles including the regulation of access and usage policies regarding data chains. Therefore, no end-to-end data exchange and cooperation has been achieved as of today. + +### Benefits for OEM, SME and Solution Provider +#### OEM +For OEM and large automotive suppliers: The Traceability solution from Catena-X enables companies to identify products affected by a defect faster and more precisely and thus avoiding general and inaccurate recalls. Through this targeted containment, companies can save both time and money with fewer actions for their customers. Moreover, the Traceability solution enables businesses to rapidly identify the affected part and the corresponding supplier after receiving an alert from the customer. This leads to faster and, therefore, cheaper problem-solving for all parties and less complicated claim management. Furthermore, suppliers can prove compliance of their supply chain to upcoming regulations such as the Supply Chain Act. + +#### SME +The developed and simple-to-use Traceability solutions support SMEs in their mission to digitize the shop floor and communication with customers and suppliers. Today, in order to provide data to their customers and suppliers, SMEs are obligated to use several, proprietary B2B-interfaces from their customers. With Catena-X aiming to have only one digital interface for all customers and suppliers, it increases the ease of data exchange and saves IT resources. Furthermore, due to the Catena-X data sovereignty principles, all participants know what happens with their data. This increases trust in the data exchange. + +#### Solution Provider +Solution providers have the potential to scale customer groups and access new market potentials via marketplace and shared service network. + +## Customer Journey + +With the Traceability KIT, we support the Catena-X customer journey for our adopters and solutions providers. + +![Customer Journey](assets/traceability_customer-journey.png) + + + + + + +## Further Explanations + +### Example - Industry Problem +The KIT enables business to start Quality Investigations and send Quality Alerts in a standardized way while already knowing which parts of your direct customer and suppliers are affected and which are not. + +Through the introduction of unique Catena-X IDs, companies can register digital twins for vehicles, products, components, and raw materials and uniquely identify them within the whole Catena-X ecosystem. Building on that, it is possible to interconnect the registered digital twins of different companies to create a coherent automotive data chain from end-to-end. Furthermore, those twins can easily be complemented with further data like material information to enable further use cases like Circular Economy. + +### Video +The following video gives an overview of the presented Traceability Use Case. + + + + + + + + diff --git a/docs-kits/kits/Traceability Kit/page_changelog.md b/docs-kits/kits/Traceability Kit/page_changelog.md deleted file mode 100644 index 443fe8010a0..00000000000 --- a/docs-kits/kits/Traceability Kit/page_changelog.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -id: Traceability Kit Changelog -title: Changelog -description: 'Traceability Kit' -sidebar_position: 1 ---- - -![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) - -### Traceability KIT - -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 - -Compatible for release 3.1. - -### Added - -- **Adoption View:** - - Traceability tutorial video - - Customer journey - -### Changed - -- ./. - -### Removed - -- ./. - -## [1.0.0] - 2023-04-12 - -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 - -- ./. - -### Removed - -- ./. diff --git a/docs-kits/kits/Traceability Kit/page_changelog.mdx b/docs-kits/kits/Traceability Kit/page_changelog.mdx new file mode 100644 index 00000000000..8d59480945e --- /dev/null +++ b/docs-kits/kits/Traceability Kit/page_changelog.mdx @@ -0,0 +1,157 @@ +--- +id: Traceability Kit Changelog +title: Changelog +description: 'Traceability Kit' +sidebar_position: 0 +--- + + + + +import Notice from './part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + +### Traceability KIT + +All notable changes to this Kit will be documented in this file. + +## [3.0.0] - 2023-11-29 + +Compatible for release 23.12. + +### Added + +- **Business View:** + - ./. +- **Architecture View:** + - Added assumptions and non-functional requirements for Traceability architecture +- **Operation View:** + - ./. +- **Development View:** + - **Data Provider:** + - Added a description of the purpose why `assetLifecylePhase` was added as specific asset ID + - **App Provider:** + - ./. + +### Changed + +- **General:** + - Restructure from adoption, operation and development view to business, architecture, operation and development view + - License KIT to CC-BY-4.0 +- **Business View:** + - ./. +- **Architecture View:** + - Update links to the latest versions of the Catena-X standards +- **Operation View:** + - ./. +- **Development View:** + - **Data Provider:** + - Updated aspect model SingleLevelBoMAsPlanned from version 1.1.0 to 2.0.0 + - Updated aspect model SingleLevelBomAsBuilt from version 1.0.0 to 2.0.0 + - Updated example for creation of the aspect model SingleLevelBomAsBuilt regarding version 2.0.0 + - Updated EDC asset props for unique ID push + - **App Provider:** + - ./. + +### Removed + +- **Business View:** + - ./. +- **Architecture View:** + - ./. +- **Operation View:** + - ./. +- **Development View:** + - **Data Provider:** + - ./. + - **App Provider:** + - ./. + +## [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 + - Updated purpose for Unique ID Push notifications to be compliant to the framework agreement for Traceability + +### Removed + +- **Adoption View:** + - Policy payloads are removed and replaced by specific documentation links + +## [1.0.1] - 2023-04-14 + +Compatible for release 3.1. + +### Added + +- **Adoption View:** + - Traceability tutorial video + - Customer journey + +### Changed + +- ./. + +### Removed + +- ./. + +## [1.0.0] - 2023-04-12 + +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 + +- ./. + +### Removed + +- ./. + + + diff --git a/docs-kits/kits/Traceability Kit/page_software-operation-view.md b/docs-kits/kits/Traceability Kit/page_software-operation-view.md deleted file mode 100644 index 480b1e691f4..00000000000 --- a/docs-kits/kits/Traceability Kit/page_software-operation-view.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: Operation View Traceability Kit -title: Operation View -description: 'Traceability Kit' -sidebar_position: 3 ---- - -![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) - -### Traceability KIT - - - -Based on the information provided in this KIT, it is possible to create and operate an own, custom -Traceability app. One open-source example is the **Trace-X app** in conjunction with the **Simple -Data Exchanger (SDE)** for data provisioning. For further information regarding -their usage, configuration and deployment, follow these resources: - -- [Trace-X Frontend GitHub Repository](https://github.com/eclipse-tractusx/traceability-foss) -- [Trace-X Backend GitHub Repository](https://github.com/eclipse-tractusx/traceability-foss) -- [Trace-X Installation Guide](https://github.com/eclipse-tractusx/traceability-foss/blob/main/frontend/INSTALL.md) -- [SDE Frontend GitHub Repository](https://github.com/eclipse-tractusx/dft-frontend) -- [SDE Backend GitHub Repository](https://github.com/eclipse-tractusx/dft-backend) diff --git a/docs-kits/kits/Traceability Kit/page_software-operation-view.mdx b/docs-kits/kits/Traceability Kit/page_software-operation-view.mdx new file mode 100644 index 00000000000..5fe09f0fb9b --- /dev/null +++ b/docs-kits/kits/Traceability Kit/page_software-operation-view.mdx @@ -0,0 +1,48 @@ +--- +id: Operation View Traceability Kit +title: Operation View +description: 'Traceability Kit' +sidebar_position: 3 +--- + + + +import Notice from './part_notice.mdx' + +![Traceability kit banner](@site/static/img/doc-traceability_header-minified.png) + + +The following page offers information on how to operate and deploy a Traceability application. + +Based on the information provided in this KIT, it is possible to create and operate an own, custom +Traceability app. One open-source example is the **Trace-X app** in conjunction with the **Simple +Data Exchanger (SDE)** for data provisioning. For further information regarding +their usage, configuration and deployment, follow these resources: + +- [Trace-X Frontend GitHub Repository](https://github.com/eclipse-tractusx/traceability-foss) +- [Trace-X Backend GitHub Repository](https://github.com/eclipse-tractusx/traceability-foss) +- [Trace-X Installation Guide](https://github.com/eclipse-tractusx/traceability-foss/blob/main/frontend/INSTALL.md) +- [SDE Frontend GitHub Repository](https://github.com/eclipse-tractusx/dft-frontend) +- [SDE Backend GitHub Repository](https://github.com/eclipse-tractusx/dft-backend) + + + + diff --git a/docs-kits/kits/Traceability Kit/part_notice.mdx b/docs-kits/kits/Traceability Kit/part_notice.mdx new file mode 100644 index 00000000000..093d879433d --- /dev/null +++ b/docs-kits/kits/Traceability Kit/part_notice.mdx @@ -0,0 +1,39 @@ +--- +sidebar_class_name: hidden +--- + + + +## NOTICE + +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 BASF SE +- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML) +- SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG +- SPDX-FileCopyrightText: 2023 Mercedes Benz AG +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 Siemens AG +- SPDX-FileCopyrightText: 2023 T-Systems International GmbH +- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version) 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 bdbe5c2fa89..d165b83c11f 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 @@ -79,7 +79,7 @@ Through the introduction of unique Catena-X IDs, companies can register digital The following video gives an overview of the presented Traceability Use Case. diff --git a/docs-kits_versioned_docs/version-3.1.0/kits/Traceability Kit/page_adoption-view.md b/docs-kits_versioned_docs/version-3.1.0/kits/Traceability Kit/page_adoption-view.md index 5406c98944c..0016803c319 100644 --- a/docs-kits_versioned_docs/version-3.1.0/kits/Traceability Kit/page_adoption-view.md +++ b/docs-kits_versioned_docs/version-3.1.0/kits/Traceability Kit/page_adoption-view.md @@ -79,7 +79,7 @@ Through the introduction of unique Catena-X IDs, companies can register digital The following video gives an overview of the presented Traceability Use Case. diff --git a/src/css/custom.css b/src/css/custom.css index f52e8568e34..129336ec52e 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -184,6 +184,10 @@ --ifm-footer-background-color: #000; } +.hidden { + display: none !important; +} + /* Media Queries */ @media screen and (max-width: 1250px) { .navbar__items { diff --git a/static/video/traceability-video-9min-UT.mp4 b/static/video/traceability-video-9min-UT.mp4 deleted file mode 100644 index d336022e35b..00000000000 Binary files a/static/video/traceability-video-9min-UT.mp4 and /dev/null differ