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 index afc543ee8cd..91be16ba70c 100644 --- 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 @@ -35,7 +35,8 @@ The traceability app providers are supposed to implement the capabilities to ena This feature will enable the whole industry to exchange and act upon quality issues in a more standardized, integrated, accelerated and precise manner in order to streamline claim management, avoid general and inaccurate recalls as well as reduce cost and safeguard brand reputation. In order to uniquely reference the affected parts across the network in the context of a quality incident, the exchange of quality notifications uses Catena-X Unique ID, which are the network-wide unique identifiers for a serialized part or batch, for which a digital twin has been created. Therefore, an app provider should also deliver capabilities for standardized creation of digital twins of vehicles, parts and materials as described in the [Industry Core KIT](../../../category/industry-core-kit) and [Digital Twin KIT](../../../category/digital-twin-kit). -![Quality Notifications](../assets/quality_notifications.png) + +![Quality Notifications](../assets/quality_notifications.svg) ### Quality Notification Process The notification process takes place between traceability applications or application stacks, and the focus is on minimal interaction, which must be supported by all applications participating in a quality notification or quality investigation scenario. This minimal interaction includes sending and receiving of quality notification as well as updating of the notification state. Application internals like user journeys, process steps or workflows for notification creation and management in an application are not standardized within Catena-X, and therefore omitted. @@ -46,7 +47,32 @@ The notification states and their cycle are described in the following figure. ### Quality Notification API A standardized set of APIs and payloads are specified to enable partners to send quality notifications in a standardized way while already knowing which parts (i.e., serialized parts or batches) and which direct customers or suppliers are affected. Notifications are - in contrast to classical data offers in Catena-X which is created for consumption by external stakeholders - a way to push notification related data from a sender to a receiver. For now, this notification API is limited to the sending and receiving of quality notifications as well as the update of the notification status following a state model. It is important to mention that the notification API shall be implemented into each participant's traceability solution or solution stack in order to be able to receive information related to quality issues. The implemented endpoints shall be able to process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. -Meanwhile, this notification API shall only be accessible after successful contract negotiation via Connector based on [Dataspace Protocol (DSP)](https://docs.internationaldataspaces.org/dataspace-protocol/), since the API is made available as part of an EDC data asset with usage policy attached. Please refer to the Notification API ([v1.2.1](../openapi/notifications_1-2-1.yaml), [v2.0.0](../openapi/notifications_2-0-0.yaml)) for more details. +Meanwhile, this notification API shall only be accessible after successful contract negotiation via Connector based on [Dataspace Protocol (DSP)](https://docs.internationaldataspaces.org/dataspace-protocol/), since the API is made available as part of an EDC data asset with usage policy attached. Please refer to the corresponding Notification API specifications for more details: +- [Notification API (v1.2.1)](../openapi/notifications_1-2-1.yaml) +- [Notification API (v2.0.0)](../openapi/notifications_2-0-0.yaml) + +> :raised_hand: For the current release, **version 1.2.1 is mandatory** and must be supported by every App provider. The newer version 2.0.0 can be supported optionally. + +## Block Notifications +While quality notifications are primarily aimed at (first) contact between business partners, block notifications represent an extended form of data exchange in order to actively initiate an immediate measure to block or sort out the produced parts at the customer's production or logistics. As the quality notifications, block notifications take place between traceability applications or other application stacks, so that this functionality must be implemented by both business partners application. + +In this case, block notifications include a **notification status similar to quality notifications** to track communication, but **also include a new status model** for each individual part of the block notification to provide additional information. For example, whether the part was blocked or whether the process to block a part was canceled. + +> :raised_hand: Since the Catena-x unique ID is used for the individually listed (damaged) parts in the block notification, the app provider should also provide functions for the standardized creation of digital twins of vehicles, parts and materials, as already mentioned in the quality notifications section. + +### Block Status Model +In order to track the blocking process in the Catena X network, a defined status model is used for each part of the block notification: +![Block Status Model](../assets/block-notification-state-model.svg) + +- ACTIVE means that the part has been identified as a damaged and safety-critical part and must therefore be blocked on the customer side. +- PART_BLOCKED is used when the recipient has received the block notification and actually blocks / sorts out the damaged parts as a measure. +- CANCELED serves as the update status of the component originally identified to be blocked if the supplier subsequently determines that the original part does meet safety requirements, is not damaged or that the information was sent by mistake. This status can also be set by the manufacturer if, after an (initial) analysis, the part does not require a block. + +### Block Notification API +A standardized API and corresponding payloads are specified for block notification to enable and ensure the exchange of information that is critical to the blocking process in a standardized way. At this point, the notification API is focused on sending and receiving notifications with a full stack of block information and on updating a previously sent notification by changing the block status. The implemented endpoints shall be able to process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. Meanwhile, the Block Notification API shall only be accessible after successful contract negotiation via Connector based on [Dataspace Protocol (DSP)](https://docs.internationaldataspaces.org/dataspace-protocol/), since the API is made available as part of an EDC data asset with usage policy attached. Please refer to the corresponding Block Notification API specification for more details: +- [Block Notification API (v1.0.0)](../openapi/block-notifications-1-0-0.yaml) + +> :raised_hand: For the current release, **version 1.0.0 is optional** and MUST be supported by every App provider from the next (major) release. The block notifications are not standardized yet, but will be released as a new optional functionality in the CX-0125 Traceability Use Case Standard as of the next release 25.03. ## Asset Registration via Connector Since the notification APIs are published towards the network using a data asset/contract definition in terms of the dataspace protocol (DSP), there are general guidelines defined for registering a notification receiving endpoint within a data asset. The traceability solutions are supposed to implement a similar data asset with the same structure and provisioning towards Catena-X. @@ -57,9 +83,11 @@ The notification endpoint providers must set properties `dct:type` and `cx-commo In general, during EDC asset creation, the notification API version needs to provided for `cx-common:version` as specified in OpenAPI documentation. For `dct:type` the following asset typizations should be used during implementation: - ReceiveQualityInvestigationNotification -- ReceiveQualityAlertNotification -- ReceiveQualityAlertNotification - UpdateQualityInvestigationNotification +- ReceiveQualityAlertNotification +- UpdateQualityAlertNotification +- ReceiveBlockNotification +- UpdateBlockNotification Please refer to the [Digital Twin KIT](../../../category/digital-twin-kit) for more details. @@ -100,7 +128,9 @@ For general guidelines for policy creation, please refer to [Industry Core KIT]( It is possible to restrict visibility of data offer for notification API with access policy either for members of Catena-X (“Membership”) and one or several Data Consumers identified by a specific business partner number ("BusinessPartnerNumber"). As for usage policy, participants and related services must restrict the data usage for notification endpoints by using the following policy rules: - Data Exchange Governance (leftOperand: “FrameworkAgreement”) – The official "Data Exchange Governance" is published on [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) -- at least one use case purpose (“UsagePurpose”) from the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). +- at least one use case purpose (“UsagePurpose”) from the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile) + - for quality notifications, the corresponding usage policy MUST be used (leftOperand: “qualityNotifications”) + - for block notifications, the same usage policy as quality notifications MUST be used (leftOperand: “qualityNotifications”) Additionally, respective usage policies MAY include the following policy rule: - Reference Contract (“ContractReference”). diff --git a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png deleted file mode 100644 index 514bafb2f38..00000000000 Binary files a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png and /dev/null differ diff --git a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg new file mode 100644 index 00000000000..da4412718ef --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg @@ -0,0 +1,4 @@ + + + +

Catena-X Core Services
«Catena-X Partner»
Traceability at Another Catena-X Partner
«Catena-X Partner»
Traceability at Catena-X Partner
Register Digital Twins 
Lookup EDC adress
 
for Catena-X partners
«Component»
Data Provisioning
Fetch Data from Digital Twins 
Optionally: Lookup Digital Twins
«Component»
Traceability App
«Service»
Eclipse Dataspace
Connector
(EDC)
Internal Systems
«Service»
Eclipse Dataspace
Connector
(EDC)
Optional: 

«Service»
Item Relationship Service
(IRS)
Internal Systems
«Service»
EDC Discovery
«Service»
Digital Twin Registry
«Service»
Digital Twin Registry
DTR via EDC:
Lookup Digital Twins for Catena-X Partners

Register Quality Investigation & Alert Topics
as EDC Assets

Register Block Information as EDC Assets

Receive and send
 Quality Investigation & Alert notifications

Receive and send Block notifications

Optionally: Fetch Data from Digital Twins 
Lookup EDC adress
 
for Catena-X partners
DTR via EDC:
Lookup Digital Twins for Catena-X Partners

Register Submodels as EDC Assets

Process requests for EDC Assets

Register Unique ID Push Topics as EDC Assets

Receive and send Unique ID Push notifications
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg.license similarity index 98% rename from docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license rename to docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg.license index 725b4f88d99..7208212b02c 100644 --- a/docs-kits/kits/Traceability Kit/assets/architecture_level_1.png.license +++ b/docs-kits/kits/Traceability Kit/assets/architecture_level_1.svg.license @@ -12,4 +12,4 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - 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 +- 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/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg new file mode 100644 index 00000000000..682dd0a849b --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg @@ -0,0 +1,4 @@ + + + +
Scenario 2 (Update)
Block information of one or more parts 
was sent by mistake. Therefore, the 
block status of the previously sent parts 
must be updated.

Note: The CANCELED status can also 
be updated by the recipient if it has 
been determined that the part is faultless 
and therefore does not need to be 
sorted out. 
Update Block Notification
Scenario 1 (Default)
Block information was sent for faulty 
parts that needs to be sorted out.
Scenario 1 (Update)
Parts were blocked and therefore the 
status was updated.
Receiver


Block Notifcation
Data
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903
ID: 864287306


Block Notifcation
Data
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903


. . .
Block Notifcation
Data
ID: 884267902
ID: 864267903
Block Notifcation
Data
Block Notifcation
Data
Block Notification
Data
Receive Block
Notification
Update Block 
Notification
ONLY status update
BlockStatus: 
PART_BLOCKED
BlockStatus: 
PART_BLOCKED
Sender


. . .
Block Notifcation
Data
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903
Data: all block information
Status: VALID
VALID
ID: 864287306


. . .
Block Notifcation
Data
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903
Data: all block information
Status: VALID
VALID
ID: 864287306


. . .
Block Notifcation
Data
Data: all block information
Status: VALID
ID: 884267902
VALID
Data: all block information
Status: VALID
VALID
ID: 864267903
Data: all block information
Status: VALID
VALID
ID: 864287306


. . .
Block Notifcation
Data
Data: block information
BlockStatus: 
ID: 884267902
Data: block information
ID: 864267903
Data: block information
ID: 864287306
Block Notifcation
Data
Block Notifcation
Data
Block Notification
Status Update
ACTIVE
BlockStatus: 
ACTIVE
BlockStatus: 
ACTIVE
Block Notifcation
Data


Block Notifcation
Data


Block Notifcation
Data


. . .
Block Notification
Status Update
ID: 864287306
ONLY status update
BlockStatus: 
CANCELED
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg.license b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg.license new file mode 100644 index 00000000000..ae4bfbd15fb --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model-interaction.svg.license @@ -0,0 +1,6 @@ +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: 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2024 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/kits/Traceability Kit/assets/block-notification-state-model.svg b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model.svg new file mode 100644 index 00000000000..a9b1bcc4e99 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model.svg @@ -0,0 +1,4 @@ + + + +
ACTIVE
CANCELED
ONLY by 
the Sender
by the Sender OR
the Receiver
Legend
Sender
Receiver
PART_BLOCKED
ONLY by
the Receiver
X
X
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/block-notification-state-model.svg.license b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model.svg.license new file mode 100644 index 00000000000..ae4bfbd15fb --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block-notification-state-model.svg.license @@ -0,0 +1,6 @@ +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: 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2024 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/kits/Traceability Kit/assets/block_notifications.svg b/docs-kits/kits/Traceability Kit/assets/block_notifications.svg new file mode 100644 index 00000000000..4c375ece037 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block_notifications.svg @@ -0,0 +1,4 @@ + + + +
B
BLOCK INFORMATION - BOTTOM UP
Tier-n
Tier-2
Tier-1
OEM
Field
Localization and sorting out the affected parts in the production or logitics process based on stuctured data
Identification of affected components, which should be blocked based on the current analysis
NO action needed, if the defective parts were sorted out before installation
X
Z
W
c
2
a
Identification of potential issues
Identification of affected components with customer
Identification of affected components with customer
Analysis and containment of affected vehicles
Countermeasures for affected vehicles
PREVENTIVE QUALITY ALERTS - BOTTOM UP
Tier-n
Tier-2
Tier-1
OEM
Field
B
x
y
z
w
b
c
A
1
2
a
b
Y
potential immediate measure 
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/assets/block_notifications.svg.license b/docs-kits/kits/Traceability Kit/assets/block_notifications.svg.license new file mode 100644 index 00000000000..ae4bfbd15fb --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/block_notifications.svg.license @@ -0,0 +1,6 @@ +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: 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2024 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/kits/Traceability Kit/assets/quality_notifications.svg b/docs-kits/kits/Traceability Kit/assets/quality_notifications.svg new file mode 100644 index 00000000000..c0d23cd0390 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/assets/quality_notifications.svg @@ -0,0 +1,4 @@ + + + +
Identification of potential issues
Identification of affected components with customer
Identification of affected components with customer
Analysis and containment of affected vehicles
Countermeasures for affected vehicles
PREVENTIVE QUALITY ALERTS - BOTTOM UP
Tier-n
Tier-2
Tier-1
OEM
Field
B
x
y
z
w
b
c
A
1
2
a
PREVENTIVE QUALITY INVESTIGATION - TOP DOWN
Frequent error
Analysis & containment of relevant components
Identification & data exchange with supplier
Cause analysis & countermeasures
Tier-n
Tier-2
Tier-1
OEM
Field
B
X
Y
Z
W
b
c
A
1
2
a
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg b/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg new file mode 100644 index 00000000000..6609f40dfb7 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg @@ -0,0 +1,4 @@ + + + +
RECEIVER
SENDER
EDC
Some (Traceability) App
Identify affected Part(s) /
Batch(es) who needs to be 
blocked / sorted out
Identify BPN for affected
Part(s) / Batch(es)
Create Notification
Status:= CREATED
[05]
Create Block Status for each 
affected Part(s) / Batch(es).
Block Status:= ACTIVE
Update Notification
Status:= SENT
Update Notification
Status:= RECEIVED
Notification 
EDC Adapter
Find and Select
Contract
EDC
Some (Traceability) App
Resolve EDC Endpoint
OK
Send Notification Update
Fetch 
Catalog
Initiate Contract 
Negotiation
Contract 
Negotiation
Establish 
Channel
POST /public/...
POST /public/...
POST /notifications/
blocknotification/receive
BPN of supply chain partner (as given in existing notification)
Find the correct contract offer with:

"asset:Prop:notificationtype" : "blocknotification",
"asset:prop:notificationmethod" : "receive"
The http path depends on the DataAddress in the EDC Data Asset. Thus, it depends on the (Trace) app.
201 OK
Discovery
Service
Fetch 
Catalog
201 OK
201 OK
201 OK
Some 
(Traceability) App
Notification 
EDC Adapter
EDC
Discovery
Service
EDC
Some 
(Traceability) App
OK
[01]
Create EDC Asset for 
"ReceiveBlockNotification" 
with DataAddress as HTTP 
POST endpoint
[02]
[03]
[04]
[06]
Not mandatory as the interaction with the EDC can be implemented also in an (traceabililty) app.

However, a similar functionality (e.g. fetch catalog) - as shown below - must be provided.
[07]
[08]
[09]
Payload as described in the Block Notification API specification
[10]
[11]
[12]
[13]
[13]
[14]
Initiate Data 
Transfer
[15]
[16]
[17]
Payload as described in the Block Notification API specification
[18]
[19]
Payload as described in the Block Notification API specification
[20]
[21]
[22]
[23]
[24]
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg.license b/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg.license new file mode 100644 index 00000000000..ae4bfbd15fb --- /dev/null +++ b/docs-kits/kits/Traceability Kit/diagrams/block-notification-send-receive.svg.license @@ -0,0 +1,6 @@ +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: 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2024 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/kits/Traceability Kit/diagrams/block-notification-update-status.svg b/docs-kits/kits/Traceability Kit/diagrams/block-notification-update-status.svg new file mode 100644 index 00000000000..1defb8e02ba --- /dev/null +++ b/docs-kits/kits/Traceability Kit/diagrams/block-notification-update-status.svg @@ -0,0 +1,4 @@ + + + +
RECEIVER
SENDER
EDC
Some (Traceability) App
Identify affected Part(s) /
Batch(es) whose block status
needs to be updated
Identify BPN for affected
Part(s) / Batch(es)
Create Notification
Status:= CREATED
[05]
Change Block Status of the 
affected Part(s) / Batch(es) 
that needs to be updated
(according to the status model)
Update Notification
Status:= SENT
Update Notification
Status:= RECEIVED
Notification 
EDC Adapter
Find and Select
Contract
EDC
Some (Traceability) App
Resolve EDC Endpoint
OK
Send Notification Update
Fetch 
Catalog
Initiate Contract 
Negotiation
Contract 
Negotiation
Establish 
Channel
POST /public/...
POST /public/...
POST /notifications/
blocknotification/update
BPN of supply chain partner (as given in existing notification)
Find the correct contract offer with:

"asset:Prop:notificationtype" : "blocknotification",
"asset:prop:notificationmethod" : "update"
The http path depends on the DataAddress in the EDC Data Asset. Thus, it depends on the (Trace) app.
201 OK
Discovery
Service
Fetch 
Catalog
201 OK
201 OK
201 OK
Some 
(Traceability) App
Notification 
EDC Adapter
EDC
Discovery
Service
EDC
Some 
(Traceability) App
Depending on whether the process for block parts was canceled or parts were actually blocked and sorted out, a different status is sent during an update.
OK
[01]
Create EDC Asset for 
"UpdateBlockNotification" 
with DataAddress as HTTP 
POST endpoint
[02]
[03]
[04]
[06]
Not mandatory as the interaction with the EDC can be implemented also in an (traceabililty) app.

However, a similar functionality (e.g. fetch catalog) - as shown below - must be provided.
[07]
[08]
[09]
Payload as described in the Block Notification API specification
[10]
[11]
[12]
[13]
[13]
[14]
Initiate Data 
Transfer
[15]
[16]
[17]
Payload as described in the Block Notification API specification
[18]
[19]
Payload as described in the Block Notification API specification
[20]
[21]
[22]
[23]
[24]
 \ No newline at end of file diff --git a/docs-kits/kits/Traceability Kit/diagrams/block-notification-update-status.svg.license b/docs-kits/kits/Traceability Kit/diagrams/block-notification-update-status.svg.license new file mode 100644 index 00000000000..ae4bfbd15fb --- /dev/null +++ b/docs-kits/kits/Traceability Kit/diagrams/block-notification-update-status.svg.license @@ -0,0 +1,6 @@ +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: 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +- SPDX-FileCopyrightText: 2024 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/kits/Traceability Kit/openapi/block-notifications-1-0-0.yaml b/docs-kits/kits/Traceability Kit/openapi/block-notifications-1-0-0.yaml new file mode 100644 index 00000000000..bc9173bf9f7 --- /dev/null +++ b/docs-kits/kits/Traceability Kit/openapi/block-notifications-1-0-0.yaml @@ -0,0 +1,602 @@ +openapi: '3.0.3' +info: + title: Block Notification API + version: '1.0.0' + description: "The blocking process is a process in the automotive industry to segregate or quarantine nonconforming parts in the supply chain to prevent using them in the production process. Therefore, the supplier must send all relevant information to the customer, so that he is able to identify the affected parts for example at the assembly line or in logistics. \n\n This API is to be used to transfer this information in a standardized manner and to trace the individual parts back to see whether they have been blocked and sorted out on the customer side in order to prevent subsequent damage or major product recalls. In addition, the notification is intended to improve the quality and speed of the block information provided." + license: + name: Apache License v2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 + +servers: +- url: https://example.com/api/v1 + variables: + api-version: + default: '1.0.0' + +paths: + + # Path to send and receive block notifications + /block-notification/receive: + post: + tags: + - Block Notification + requestBody: + $ref: '#/components/requestBodies/BlockNotificationReceive' + responses: + "201": + $ref: '#/components/responses/Successful' + "400": + $ref: '#/components/responses/Malformed' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFoundError' + "405": + $ref: '#/components/responses/Duplication' + "422": + $ref: '#/components/responses/SemanticError' + + # Path to send and receive a status update of a existing block notifications + /block-notification/update: + post: + tags: + - Block Notification + requestBody: + $ref: '#/components/requestBodies/BlockNotificationUpdate' + responses: + "201": + $ref: '#/components/responses/Successful' + "400": + $ref: '#/components/responses/Malformed' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFoundError' + "405": + $ref: '#/components/responses/Duplication' + "422": + $ref: '#/components/responses/SemanticError' + +components: + + # Schemas to build up the request body and the reponses + schemas: + BlockNotificationReceive: + type: object + description: "Request schema to send block notifications." + properties: + header: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic' + content: + $ref: '#/components/schemas/NotificationContentReceive' + required: + - header + - content + + BlockNotificationUpdate: + type: object + description: "Request body schema to send a status update for an existing block notification." + properties: + header: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic' + content: + $ref: '#/components/schemas/NotificationContentUpdate' + required: + - header + - content + + # Schemas to build up the header + urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic: + description: Characteristic describing the common shared aspect Message Header + type: object + properties: + messageId: + description: "Unique ID identifying the message. The purpose of the ID is\ + \ to uniquely identify a single message, therefore it MUST not be reused." + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' + context: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic' + sentDateTime: + description: Time zone aware timestamp holding the date and the time the + message was sent by the sending party. The value MUST be formatted according + to the ISO 8601 standard + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + senderBpn: + description: The Business Partner Number of the sending party. The value + MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints + are defined in the corresponding standard + $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' + receiverBpn: + description: The Business Partner Number of the receiving party. The value + MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints + are defined in the corresponding standard. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' + expectedResponseBy: + description: Time zone aware timestamp holding the date and time by which + the sending party expects a certain type of response from the receiving + party. The meaning and interpretation of the fields's value are context-bound + and MUST therefore be defined by any business domain or platform capability + making use of it. The value MUST be formatted according to the ISO 8601 + standard + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + relatedMessageId: + description: Unique ID identifying a message somehow related to the current + one + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' + version: + description: The unique identifier of the aspect model defining the structure + and the semantics of the message's header. The version number should reflect + the versioning schema of aspect models in Catena-X. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait' + required: + - messageId + - context + - sentDateTime + - senderBpn + - receiverBpn + - version + + urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait: + type: string + description: "The fully anonymous Catena-X ID of the serialized part or\ + \ batch, valid for the Catena-X dataspace. \n\nThe provided regular expression ensures that the UUID is composed\ + \ of five groups of characters separated by hyphens, in the form 8-4-4-4-12\ + \ for a total of 36 characters (32 hexadecimal characters and 4 hyphens),\ + \ optionally prefixed by \"urn:uuid:\" to make it an IRI." + pattern: "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)" + + urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic: + type: string + description: |- + Information about the context the message should be considered in. + The value MUST consist of two parts: an identifier of the context (e.g. business domain, etc.) followed by a version number. + Both the identifier and the version number MUST correspond to the content of the message. + If the content of a message is described by an aspect model available in the Catena-X Semantic Hub, then the unique identifier of this semantic model (e.g. urn:samm:io.catenax.:1.x.x) MUST be used as a value of the context field. This is considered the default case. + In all other cases the value of the context field MUST follow the pattern --:<[major] version> (e.g. TRACE-QM-Alert:1.x.x). + Versioning only refers to major versions in both default and fallback cases. + Note: The version of the message's header is specified in the version field. + example: 'Traceability-BlockNotification:1.0.0' + + urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp: + type: string + pattern: "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\\ + .[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?" + description: Describes a Property which contains the date and time with an optional + timezone. + example: '2024-10-07T10:15+00:00' + + urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait: + type: string + description: "The provided regular expression ensures that the BPNL is composed\ + \ of prefix 'BPNL', 10 digits and two alphanumeric letters." + pattern: "^BPNL[a-zA-Z0-9]{12}$" + + urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait: + type: string + description: Constraint for defining a SemVer version. + pattern: "^(0|[1-9][0-9]*).(0|[1-9][0-9]*).(0|[1-9][0-9]*)(-(0|[1-9A-Za-z-][0-9A-Za-z-]*)(.[0-9A-Za-z-]+)*)?([0-9A-Za-z-]+(.[0-9A-Za-z-]+)*)?$" + example: '3.0.0' + + # Schemas to build up the content (default notification) + urn_samm_io.catenax.block_notification_receive_1.0.0_PartBlockingInformationSet: + description: The characteristic of the part blocking information defined as + an Array Set. + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PartBlockingInformationEntity' + uniqueItems: true + + urn_samm_io.catenax.block_notification_data_1.0.0_PartBlockingInformationEntity: + description: The entitiy of the part blocking information Array Set. + type: object + properties: + catenaXId: + description: "The fully anonymous Catena-X ID of the serialized part or\ + \ batch, valid for the Catena-X dataspace." + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' + blockStatus: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_1.0.0_BlockStatus' + componentLevelContainment: + description: Section with blocking information at component level. + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_ComponentLevelContainmentCharacteristic' + periodAndVolumeLevelContainment: + description: Section with blocking information at period and volume level. + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PeriodAndVolumeLevelContainmentCharacteristic' + locationInTheContainer: + description: 'Object which contain information regarding the locality of + the part within a small load carrier. ' + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_LocationInTheContainerCharacteristic' + required: + - catenaXId + - blockStatus + - componentLevelContainment + - periodAndVolumeLevelContainment + + urn_samm_io.catenax.block_notification_1.0.0_BlockStatus: + type: string + description: "Child-element of the partBlockingInformation array.\n\nProvides\ + \ information about the status of the individual part within a blocking\ + \ notification that must be blocked for security reasons. \n\nACTIVE means\ + \ that the part has been identified as a damaged and safety-critical part\ + \ and must therefore be blocked on the customer side.\n\nPART_BLOCKED\ + \ Status when the receiver has accepted the block and has actually blocked\ + \ the part (Note: sender must be informed!).\n\nCANCELED serves as the\ + \ update status of the component originally identified to be blocked if\ + \ the manufacturer subsequently determines that the original part does\ + \ meet safety requirements, is not damaged or that the information was\ + \ sent by mistake. " + enum: + - ACTIVE + - PART_BLOCKED + - CANCELED + + urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic: + type: string + description: "Identifies the respective address of the supplier's location + from which the corresponding components are delivered. \n\n The provided regular expression ensures that the BPNA is composed\ + \ of prefix 'BPNA', 10 digits and two alphanumeric letters." + pattern: "^BPNA[a-zA-Z0-9]{12}$" + + urn_samm_io.catenax.block_notification_data_1.0.0_IntegrationLevelCharacteristic: + type: string + description: "(E/E component generation (hardware and software) with defined\ + \ functional content and coordinated system communication) [Vehicle electrics/electronics]\t" + example: 'S18A-19-03-400' + + urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic: + type: string + description: |- + An ID that consists of two different pieces of information but at least always contains a part number: + + Part Number + identifier of a particular part design (or material used) which unambiguously identifies a part design within a single corporation, sometimes across several corporations + + Change Index (optional) + The change index corresponds to the identification of a version of a technical object (also in the technical drawing). + This provides easy-to-understand version management, which allows older variants to be clearly addressed. The first version usually has an index of 0. When changes are made, this is usually increased by 1. The current edition therefore has the highest change index. Alternatively, it is possible to represent the index in ascending order with letters, i.e. A, B, C,... Z, AA, AB, etc. + example: '884267902' + + urn_samm_io.catenax.serial_part_3.0.0_KeyTrait: + type: string + description: Constraint that ensures that the standard keys and custom key prefixes + can be used. + pattern: ^(manufacturerId|partInstanceId|batchId|van|customKey:\w+)$ + + urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic: + type: string + description: The value of an identifier. + + urn_samm_io.catenax.serial_part_3.0.0_KeyValueList: + description: "A list of key value pairs for local identifiers, which are composed\ + \ of a key and a corresponding value." + type: object + properties: + key: + description: 'The key of a local identifier. ' + $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyTrait' + value: + description: The value of an identifier. + $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic' + required: + - key + - value + + urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic: + description: "A local identifier enables identification of a part in a specific\ + \ dataspace, but is not unique in Catena-X dataspace. Multiple local identifiers\ + \ may exist. \n\n A single serialized part may have multiple attributes, that uniquely\ + \ identify a that part in a specific dataspace (e.g. the manufacturer`s dataspace)" + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyValueList' + uniqueItems: true + example: + - key: 'manufacturerId' + value: 'BPNL0123456789ZZ' + - key: 'partInstanceId' + value: 'SN12345678' + - key: 'customKey:ecuSerialNumber' + value: '220115001384267902201978150063581180' + + urn_samm_io.catenax.block_notification_data_1.0.0_ComponentLevelContainmentCharacteristic: + description: 'The characteristic of the component level containment defined + as a Object. ' + type: object + properties: + manufacturingLocationId: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic' + integrationLevel: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_IntegrationLevelCharacteristic' + customerPartId: + $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic' + localIdentifiers: + $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic' + required: + - manufacturingLocationId + - customerPartId + - localIdentifiers + + urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration: + type: string + pattern: "[a-zA-Z]*:[a-zA-Z]+" + description: Enumeration for common item units. + enum: + - unit:piece + - unit:set + - unit:pair + - unit:page + - unit:cycle + - unit:kilowattHour + - unit:gram + - unit:kilogram + - unit:tonneMetricTon + - unit:tonUsOrShortTonUkorus + - unit:ounceAvoirdupois + - unit:pound + - unit:metre + - unit:centimetre + - unit:kilometre + - unit:inch + - unit:foot + - unit:yard + - unit:squareCentimetre + - unit:squareMetre + - unit:squareInch + - unit:squareFoot + - unit:squareYard + - unit:cubicCentimetre + - unit:cubicMetre + - unit:cubicInch + - unit:cubicFoot + - unit:cubicYard + - unit:litre + - unit:millilitre + - unit:hectolitre + - unit:secondUnitOfTime + - unit:minuteUnitOfTime + - unit:hourUnitOfTime + - unit:day + + urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic: + type: number + description: The quantity value associated with the unit expressed as float. + example: 20.0 + + urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic: + description: 'The characteristic to define the quantity an value of a property. ' + type: object + properties: + itemUnit: + description: "The unit of an item. Common units may be related to mass,\ + \ count, linear, area, volume or misc." + $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration' + quantityValue: + description: The quantity value associated with the unit. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic' + required: + - itemUnit + - quantityValue + + urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryPlaceCharacteristic: + type: string + description: "The identification number of the unloading point. An unloading\ + \ point is an important part of logistics, as it describes the location\ + \ where goods can be loaded or unloaded using a means of transport. In\ + \ addition to the address itself, the spatial conditions at the unloading\ + \ point are also important. Each warehouse has its own type of unloading\ + \ point, such as a ramp that is specifically designed for loading and\ + \ unloading goods. These specific conditions are crucial for the efficient\ + \ and secure processing of deliveries.\t" + example: '22610' + + urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryNoteNumberCharacteristic: + type: string + description: "The number of the delivery note that accompanies the delivery\ + \ and shows the description, unit and quantity of goods included in the\ + \ delivery, etc..\t" + example: '68988545' + + urn_samm_io.catenax.block_notification_data_1.0.0_PackageNumberCharacteristic: + type: string + description: "Identififcation number of the package, the unit of goods and\ + \ packaging material. These can be boxes, pallets, mesh boxes, roll containers\ + \ and other loading equipment." + example: '12295140916130' + + urn_samm_io.catenax.block_notification_data_1.0.0_OrderNumberCharacteristic: + type: string + description: The order number (only for production synchronization requests + (JIS)) + example: '7334663' + + urn_samm_io.catenax.block_notification_data_1.0.0_PeriodAndVolumeLevelContainmentCharacteristic: + description: 'The characteristic of the period and volume level containment + defined as Object. ' + type: object + properties: + sizeOfProductionLot: + description: "A production lot is the combined number of products or manufactured\ + \ parts that are produced in a work process without interruption. There\ + \ is no need to convert production facilities. \t" + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' + deliveryNoteNumber: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryNoteNumberCharacteristic' + packageNumber: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PackageNumberCharacteristic' + deliveryPlace: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryPlaceCharacteristic' + deliveryDate: + description: "The date, on which the supplier handed over the shipment \ + \ to the carrier. Shiiping date of the manufacturer." + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + numberOfPartsPerDeliveryNote: + description: The quanity of delivered parts per delivery note. + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' + productionDate: + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + numberOfPartsPerPackage: + description: Number of parts, which are stored in a package. + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' + orderNumber: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_OrderNumberCharacteristic' + required: + - sizeOfProductionLot + - deliveryNoteNumber + - packageNumber + - deliveryPlace + - deliveryDate + - numberOfPartsPerDeliveryNote + - productionDate + - numberOfPartsPerPackage + + urn_samm_io.catenax.block_notification_data_1.0.0_XPositionCharacteristic: + type: string + description: "Position along the X coordinate where the faulty component\ + \ (cell) is located within the small charge carrier.\t" + example: 'F' + + urn_samm_io.catenax.block_notification_data_1.0.0_YPositionCharacteristic: + type: string + description: Position along the Y coordinate where the faulty component + (cell) is located within the small charge carrier. + example: '10' + + urn_samm_io.catenax.block_notification_data_1.0.0_SmallLoadCarrierLayerCharacteristic: + type: string + description: |- + The layer within the small load carrier in which the faulty part is located. + (Ideally if available: UCID = Unique Container ID - ID of the small load carrier in which the faulty part is located) + Packaging specific for high-voltage battery cells. Other components (e.g. penthouse are not packaged in small load carriers). + example: '53BUN6555599345283155+000000008' + + urn_samm_io.catenax.block_notification_data_1.0.0_LocationInTheContainerCharacteristic: + description: The characteristic to define the location in the container defined + as entity. + type: object + properties: + xPosition: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_XPositionCharacteristic' + yPosition: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_YPositionCharacteristic' + smallLoadCarrierLayer: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_SmallLoadCarrierLayerCharacteristic' + + # Schemas to build up the content (status udpate notification) + urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationSet: + description: The characteristic of the part blocking information defined as + an Array Set. + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationEntity' + uniqueItems: true + example: + - catenaXId: '580d3adf-1981-44a0-a214-13d6ceed9379' + blockStatus: 'PART_BLOCKED' + - catenaXId: '6a3cA7E1-1682-5F25-FE1d-cF112433C2f4' + blockStatus: 'PART_BLOCKED' + - catenaXId: '550d3swf-1845-55sw-a2s8-13d6ceed4265' + blockStatus: 'PART_BLOCKED' + + urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationEntity: + description: The entitiy of the part blocking information Array Set. + type: object + properties: + catenaXId: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' + blockStatus: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_1.0.0_BlockStatus' + required: + - catenaXId + - blockStatus + + NotificationContentReceive: + type: object + properties: + notificationStatus: + $ref: '#/components/schemas/NotificationStatus' + problemDescription: + type: string + maxLength: 1000 + example: "Gear boxes lose oil while driving." + description: A free text field which provides information why the parts from the provided list must be blocked or sorted out. + blockInformations: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_receive_1.0.0_PartBlockingInformationSet' + required: + - notificationStatus + - blockInformations + + NotificationContentUpdate: + type: object + properties: + notificationStatus: + $ref: '#/components/schemas/NotificationStatus' + updateReason: + type: string + maxLength: 1000 + example: "Defect gear boxes were sorted out to prevent major damage." + description: A free text field that informs why a previously provided list of damaged parts needs to be updated. For example, because the order to block the parts must be canceled due to a user error or because the damaged parts were sorted out by the customer and thus blocked. + blockInformations: + $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationSet' + required: + - notificationStatus + - blockInformations + + NotificationStatus: + type: string + enum: + - CREATED + - SENT + - RECEIVED + - ACKNOWLEDGED + - CLOSED + example: 'SENT' + description: The status of the block notification. The following entries are supported and allowed + + - CREATED + This status is an internal status and is used after the initial creation of a notification. It is not communicated to an other CX/business partner. + + - SENT + This status means that the notification has been sent out. This status is shown on the sender side (and not on the receiver side). + + - RECEIVED + This status means that the notification has been received by the receiver. The status is shown on sender and receiver side. It is not communicated to another CX/business partner. + + - ACKNOWLEDGED + Defines that a user has confirmed that the notification has been received. + + - CLOSED + This status is set by the initiator of the notification either to regularly close the notification (i.e., after the receiver has set the status to ACKNOWLEDGED). + + # Response Content + responses: + Successful: + description: Block notification was sent successfully. + Malformed: + description: Request body was malformed. + Unauthorized: + description: The requesting user or client is not authenticated. + Forbidden: + description: The requesting user or client is not authorized to access.resources. + NotFoundError: + description: Method not allowed. + Duplication: + description: Could not accept the sent block notification, because a block notification with that same notification ID already exists. + SemanticError: + description: Could not accept the sent block notification even though it is syntactically correct. The block notification is not accepted, because of semantic reasons (e.g., an affected item is not known by the receiver). + + # Request Body Content + requestBodies: + BlockNotificationReceive: + content: + application/json: + schema: + $ref: '#/components/schemas/BlockNotificationReceive' + BlockNotificationUpdate: + content: + application/json: + schema: + $ref: '#/components/schemas/BlockNotificationUpdate' diff --git a/docs-kits/kits/Traceability Kit/page_architecture-view.mdx b/docs-kits/kits/Traceability Kit/page_architecture-view.mdx index dac73dac88e..87e63bb698f 100644 --- a/docs-kits/kits/Traceability Kit/page_architecture-view.mdx +++ b/docs-kits/kits/Traceability Kit/page_architecture-view.mdx @@ -51,14 +51,14 @@ This KIT describes two core capabilties of Traceability: This overview shows the two core capabilities of Traceabilty and the Catena-X Core Services onto which Traceability is built and which are required by the Traceability architecture. -![Architecture - Level 1](./assets/architecture_level_1.png) +![Architecture - Level 1](./assets/architecture_level_1.svg) ### Traceability Components | Subsystem | Description | |:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Provisioning | This component extracts data from a company's internal systems, transforms it into digital twins, and publishes these digital twins in the DTR and their data in the EDC (as submodels, based on aspect models). The published data is used by Traceability apps as well as other use cases that require Traceabiilty data. | -| Traceability App | A Traceability app has two core functionalities:
  • providing an UI to show the parts manufactured by a company and published as digital twins
  • create and process quality alerts and quality investigations for quality actions
| +| Traceability App | A Traceability app has three core functionalities:
  • providing an UI to show the parts manufactured by a company and published as digital twins
  • create and process quality alerts and quality investigations for quality actions
  • create and transfer block information in real time to separate or quarantine faulty parts in the supply chain to prevent them from being used in the production process (currently optional app feature)
| | Internal Systems | These are existing internal systems of a Catena-X partner which provides data to Traceability components, e.g.,
  • for data provisioning: The data provided to Catena-X is 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. Generally, 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 @@ -85,13 +85,16 @@ The following diagram shows a basic data processing flow how a company's interna Data provisioning of Traceabilty is built on the data provisioning of the [Industry Core KIT](../Industry%20Core%20Kit/Architecture%20View%20Industry%20Core%20Kit), i.e., Traceability extends the digital twins PartType and PartInstance with additional aspect models: - Digital Twin "PartType" - + - N/A - Digital Twin "PartInstance" - - Aspect model ["TractionBatteryCode"](../Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit#tractionbatterycode) - + - Aspect model ["TractionBatteryCode"](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit#tractionbatterycode) + - Aspect model ["SoftwareInformation"](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit#softwareinformation) + - Aspect model ["CertificateSigningRequests"](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit#certificatesigningrequests) Details about these aspect models, i.e., the SAMM data model as well as example data, can be found in the [Developer View](../Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit). +> :raised_hand: Beware that the aspect models **_SoftwareInformation_** and **_CertificateSigningRequests_** are not standardized yet, but MAY be released as standardized aspect models in future releases of the CX-0125 Traceability Use Case Standard. + ### 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. @@ -119,7 +122,8 @@ This capability defines what mandatory features a Traceability app must provide | Data Sharing via [CX-0018](#standards) compliant connector | Yes | The data sharing with other Catena-X partners (for Traceability partners, these are their customers and suppliers mostly) must be done via via a [CX-0018](#standards) compliant connector (e.g. EDC). | | Data Sovereignty | Yes | The usage of data in the Traceability app is compliant with the Access and Usage Policies as defined in this KIT. | Quality Alerts | Yes | In the event of an incident the partner's value chain, the partner would like to be informed promptly and in a structured manner by the triggering partners (e.g., manufacturing problem, field problems) so that the partner can respond as quickly as possible (Supplier/Customer). In the same way, the partner wants to inform their value chain partners easily and specifically in the event of relevant incidents. The traceability apps are able to exchange the alerts in the same interoperable way. | -| Quality Investigations | Yes | For a given incident in a partner's supply chain, the partner would like to be able to narrow down the affected products as sharply as possible in order to carry out suitable actions in a targeted manner. The partners in the value chain use interoperable Traceability apps for this purpose.| +| Quality Investigations | Yes | For a given incident in a partner's supply chain, the partner would like to be able to narrow down the affected products as sharply as possible in order to carry out suitable actions in a targeted manner. The partners in the value chain use interoperable Traceability apps for this purpose.| +| Block Information | No | The blocking process is a event where faulty parts in the supply chain are separated or quarantined to prevent them from being used in the production process. Due to the criticality, this part-specific information must be forwarded to the affected manufacturers as quickly as possible so that they can react immediately to sorting out the corresponding components. To overcome this challenge, this information is provided and transmitted via a standardized API.| ### Non-Functional Requirements @@ -137,29 +141,59 @@ The notification itself has various states. The states and their cycle are descr ![Notification State Model](./assets/notification-state-model.svg) -## Runtime View +### Block Information + +The blocking process is a process in the automotive industry to segregate or quarantine nonconforming parts in the supply chain to prevent using them in the production process. Therefore, the supplier must send all relevant information to the customer, so that he is able to identify the affected parts for example at the assembly line or in logistics. + +Catena-X is to be used to transfer this information in a standardized manner and to trace the individual parts back to see whether they have been blocked and sorted out on the customer side in order to prevent subsequent damage or major product recalls. In addition, the notification is intended to improve the quality and speed of the block information provided. + +#### Block Notification Interaction + +The interaction of block notifications is based on events that can be triggered by both the sender and the recipient. These events are represented by a status model and are used to track the progress of the parts that need to be blocked or respectively sorted out by the customer. Details about these status model and the Open API specification for Block Notifications are available in the [Developer View](../Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit). + +**Scenario 1:** In this case, it is assumed that the sender sends a list of parts with the associated block information to the recipient. The block status of each part is set to ACTIVE by default. + +When all block information has been received by the recipient, checked internally, further processed and finally all affected parts were blocked or sorted out, this information is sent back to the sender through a status update (PART_BLOCKED). + +> :raised_hand: Note that the update notification whether one or more parts have been blocked and therefore sorted out by the customer is **not mandatory**. The decision to provide suppliers with this information through a feedback notification **MUST** have been negotiated and accepted by both business partners before implemented. + +**Scenario 2:** +In this case, the sender identified that the block information sent from Scenario 1 was sent incorrectly or unintentionally. + +In order to inform the recipient of this error, the block status of the affected parts is set to CANCELED via an update notification, so that these parts cannot be sorted out and used to be installed by the recipient. -### Processes for Sending, Updating and Resolving Notifications +> :raised_hand: The CANCELED status can also be updated by the recipient if it has been determined that the part(s) are faultless and therefore does not need to be sorted out. -Below the sequence for sending, updating and resolving of notifications between (traceability) applications is shown with UML sequence diagrams. In all cases, Http POST requests are used. Those Http endpoints are described in the section (TRS) Quality Notification Endpoints and EDC Contract Offerings. +![Block State Model Interaction](./assets/block-notification-state-model-interaction.svg) + +## Runtime View + +In the sub-sections below the sequence for sending, updating and resolving of notifications between (traceability) applications is shown with UML sequence diagrams. In all cases, Http POST requests are used. Those Http endpoints are described in the corresponding sections: +- [(TRS) Quality Notification Endpoints](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/App%20Provider%20Development%20View%20Traceability%20Kit#quality-notifications) +- [Block Notification Endpoints](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/App%20Provider%20Development%20View%20Traceability%20Kit#block-notifications) +- [EDC Contract Offerings](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/App%20Provider%20Development%20View%20Traceability%20Kit#asset-registration-via-connector). To read the UML sequence diagrams correctly, some remarks: - The shown Notification EDC Adapter is not mandatory. It is just one option to send a notification via the EDC control and data plane. Important is that a similar functionality must be provided/implemented by the (traceability) application vendor. The Notification EDC Adapter or a similar component / functionality will not be provided as a central service from Catena-X. - To know where a notification must be send to, the (traceability) application must resolve the BPN of the receiver. This can either be happen because the (traceability) application has this information in its data model or it could - alternatively - also be resolved e.g. via a lookup of the digital twin in the central asset administration shell (AAS) registry. - :raised_hand: The (traceability) applications that fully rely on the AAS registry and the corresponding AAS submodels can only support quality investigations. With the release of the AAS submodel SingleLevelUsageAsBuilt or a similar AAS submodel that contains the information, which supply chain partner purchased/assembled a part / batch, it is possible to also support quality alerts for those (traceability) applications. (Warnung) - The resolution of the EDC URL for a given BPN is done via the Discovery Service API. The entry for each EDC into this Discovery Service is done via the CX Portal. - In each UML sequence diagram the step [01] describes the publishing of the notification endpoints as described in the above sections - Similarly, the Http POST request and response bodies are described in the above sections +### Processes for Sending, Updating and Resolving Quality Notifications + #### Sending and Receiving of a Quality Investigation Below, the UML sequence diagram to send and receive a quality investigation is depicted. In addition to the above mentioned general remarks, the following remark: +- The status transition from SENT to RECEIVED has to be done by the sender once it received the Http status code 201 from the receiver + ![NotificationSendReceive](./diagrams/notification_send-receive.svg) #### Sending and Receiving of a Quality Alert +> :raised_hand: The (traceability) applications that fully rely on the AAS registry and the corresponding AAS submodels can only support quality investigations. With the release of the AAS submodel SingleLevelUsageAsBuilt or a similar AAS submodel that contains the information, which supply chain partner purchased/assembled a part / batch, it is possible to also support quality alerts for those (traceability) applications. Below, the UML sequence diagram to send and receive a quality alert is depicted. In addition to the above mentioned general remarks, the following remark: @@ -167,7 +201,6 @@ Below, the UML sequence diagram to send and receive a quality alert is depicted. ![NotificationSendReceiveAlert](./diagrams/notification_send-receive-alert.svg) - #### Update of a Quality Investigation Below, the UML sequence diagram to update a quality investigation is depicted. @@ -175,19 +208,33 @@ Below, the UML sequence diagram to update a quality investigation is depicted. ![NotificationUpdateInvestigation](./diagrams/notification_update-investigation.svg) #### Update of a Quality Alert +> :raised_hand: The (traceability) applications that fully rely on the AAS registry and the corresponding AAS submodels can only support quality investigations. With the release of the AAS submodel SingleLevelUsageAsBuilt or a similar AAS submodel that contains the information, which supply chain partner purchased/assembled a part / batch, it is possible to also support quality alerts for those (traceability) applications. Below, the UML sequence diagram to update a quality alert is depicted. ![NotificationUpdateAlert](./diagrams/notification_update-alert.svg) +### Processes for Sending, Updating and Resolving Block Notifications + +#### Sending and Receiving of Block Information +Below, the UML sequence diagram to send and receive a block information is depicted. + +![BlockNotificationSendReceive](./diagrams/block-notification-send-receive.svg) + +#### Update of Block Information +Below, the UML sequence diagram to update a block information is depicted. +> :raised_hand: The process for sending update notifications regarding an ongoing blocking process must be carried out in the same way as sending block information for the first time. The differences are limited to the following changes: +> - Another data asset “BlockNotificationStatusUpdate” is used for the update +> - The data model of the notification is limited to the ID and block status of a part and therefore does not include full block informations +> - Both 'CANCELED' and 'PART_BLOCKED' can be set for the status depending on which case applies to the notification + +![BlockNotificationUpdateStatus](./diagrams/block-notification-update-status.svg) + ## Standards Our relevant standards can be downloaded from the official [Catena-X Standard Library](https://catena-x.net/de/standard-library): - Traceability is built on the Industry Core. Please check the relevant [standards of the Industry Core](../Industry%20Core%20Kit/Architecture%20View%20Industry%20Core%20Kit#standards). -- [CX - 0022 Notification Process 1.1.1](https://catena-x.net/de/standard-library) -- [CX - 0023 Notification API 1.2.2](https://catena-x.net/de/standard-library) -- [CX - 0062 Traceability Notification Triangle 1.0.0](https://catena-x.net/de/standard-library) -- [CX - 0093 Aspect Model Traction Battery Code 1.0.0](https://catena-x.net/de/standard-library) +- [CX - 0125 Traceability Use Case v2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0125-TraceabilityUseCase) diff --git a/docs-kits/kits/Traceability Kit/page_business_view.mdx b/docs-kits/kits/Traceability Kit/page_business_view.mdx index 537028f4931..43e8a5b370d 100644 --- a/docs-kits/kits/Traceability Kit/page_business_view.mdx +++ b/docs-kits/kits/Traceability Kit/page_business_view.mdx @@ -79,7 +79,19 @@ In the worst case, the quality alert can result in a recall of the affected seri The following figure illustrates, how quality investigations and alerts throughout the supply chain enable quality problems to be contained quickly and precisely. -![Quality Notifications](assets/quality_notifications.png) +![Quality Notifications](assets/quality_notifications.svg) + +### Block Notifications + +Equal to quality notifications, block notifications are a form of data exchange to transfer information about defective parts in a standardized way. Quality notifications in general and quality alerts in particular can be used for the (first) mainly **unstructured** contact between business partners to initiate e.g. a supplier self-disclosure. Block notifications, in contrast, are **structured** messages. They are used to report parts with critical defects, enriched with specific information, directly to business partners, as an immediate measure potentially following a preceding quality alert. + +> :raised_hand: Detailed information of the specific data being exchanged are available in the [Development View](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Software%20Development%20View/Data%20Provider%20Development%20View%20Traceability%20Kit#aspect-models). + +In this way, the customer can react quickly and precisely locate the parts based on the block information and sort them out at an early stage to prevent subsequent damage or major recalls and thus save costs and ensure a high quality of the vehicles, delivered to the customer. Block notifications should therefore significantly simplify the data exchange of block information in a standardized way and improve speed and quality. + +The following figure gives an overview of how block notifications are exchanged between business partners: + +![Block Notifications](assets/block_notifications.svg) ### Special Characteristics Special characteristics are product or process characteristics that may have an impact on safety or regulatory compliance, fit, function, performance or further processing of the product. diff --git a/docs-kits/kits/Traceability Kit/page_changelog.mdx b/docs-kits/kits/Traceability Kit/page_changelog.mdx index 536945cd16a..a8a189cdd1f 100644 --- a/docs-kits/kits/Traceability Kit/page_changelog.mdx +++ b/docs-kits/kits/Traceability Kit/page_changelog.mdx @@ -35,15 +35,58 @@ All notable changes to this Kit will be documented in this file. Compatible for **release 24.12**. ### Added -- **Business View:** - - **Special Characteristics:** - - Added new section to introduce the special characteristics in general -- **Development View | Data Provider:** + +-**Business View:** + - **Block Notifications:** + - Added new sub-section 'Block Notifications' to introduce the new feature including a picture for further explanation + - **Special Characteristics:** + - Added new section to introduce the special characteristics in general +- **Architecture View:** + - **Traceability Components:** + - Enhanced the existing table 'Traceability Components' by adding a new line for the block notification feature + - **Functional Requirements:** + - Enhanced the existing table 'Functional Requirements' by adding a new row for the block notification feature + - **Digital Twins and Aspect Models:** + - Added references of two new aspect models (SoftwareInformation 1.0.0, CertificateSigningRequests 1.0.0) + - **Traceability Apps:** + - Added new sub-section 'Block Information' to describe the Notification State Model inclusive the corresponding state model picture + - **Runtime View:** + - Added references to the coressponding sections of the HTTP Endpoints for the notifications + - Added new sub-sections to describe the processes for sending, updating and resolving block notifications including its UML sequence diagrams + - **Standards:** + - Added reference to latest Traceability Use Case Standard v.2.0.0 +- **Development View:** + - **App Provider:** + - **Block Notifications:** + - Added new sub-sections to describe the Block Notifications state model and the new Block Notification API specification + - **Asset Creation:** + - Added two lines for the typizations 'ReceiveBlockNotification' and 'UpdateBlockNotification' of the new block notifications + - **Policy Creation:** + - Added two lines to specify the needed (usage) policies for quality- and block notifications + - **Data Provider:** - **Aspect Models:** - Added the new SpecialCharacteristics model to the aspect model overview - **Special Characteristics:** - Added a new section to describe and reference the aspect model for special characteristics including JSON examples +### Changed +- **Architecture View:** + - **Build Block View:** + - Updated the Traceability architecture picture with new description regarding Block Notifications + - **Runtime View:** + - Adapted / restructured the remarks text block to be applicable for quality- and the new block notifications +- **Development View:** + - **App Provider:** + - **Quality Notification API:** + - The last sentence, which mentions the Notification APIs, has been restructured to make the references to the Notification API specifications more visible + - **Asset Creation:** + - Fixed / changed asset typization from 'ReceiveQualityAlertNotification' to 'UpdateQualityAlertNotification' + +### Removed +- **Architecture View:** + - **Standards:** + - Removed references to deprecated Traceability standards + ## [5.1.1] - 2024-08-18 ### Changed