Skip to main content
Release: CX-Jupiter (current)

CX-0142 Shop Floor Information Service v1.0.0

ABSTRACT

A Modular Production is part of the value chain. On the one hand, it has to guarantee flexibility and availability, and on the other, it has to allow for product mixes with small lot sizes. The effects of disturbances and decisions in this network are not limited to a local area, but also have a major impact on other partners in the value chain network. It is therefore necessary to exchange values from the shop floor directly with other members of the network, such as customers or their representatives, like logisticians. This communication is realized with the Shop-Floor-Information-Service (SIS). This service provides different types of information that a factory can offer to its customers. It is not dedicated to a specific purpose, as customers may decide how to handle the information themselves.

The current version of the standard provides two different kinds of data: Production Forecasting, and Production Tracking data. To give an example of forecasting data, suppose a customer wants to know when production is expected to start. He can use the Shop-Floor-Information-Service in order to get the information either directly, via cyclic messages or via notifications when the calculated production dates change. As an example of production tracking, a customer can request certain production attributes collected during production, such as the torque of a particular process step. This data can then be used for both documentation and tracking.

In order to exchange the data the Shop-Floor-Information-Service defines the necessary data models, such as the GetProductionForecast data and the ProvideProductionForecast data model as well as GetProductionTracking data and ProvideProductionTracking data model. This data exchange mechanism between Modular Production and the data consumer is realized via the Shop-Floor-Information API.

COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD

  • Release 24.05
    • Merge CX-0068, CX-0069 and CX0075 by combining the different standards that describe the data model, the API and and the process into this combined standard.
    • Additional functionality added: production tracking aspects.
    • Update of Production Forecast Models due to update of CX-header.
  • Release 23.09
    • Initial Release

1 INTRODUCTION

1.1 AUDIENCE & SCOPE

This standard is relevant for

  • Business Application Providers: their role is to implement the Shop-Floor-Information-Service,
  • Data Providers, mainly Modular Productions: they have to provide the data required for the Shop-Floor-Information-Service,
  • Data Consumers, e.g. tier n-1 factories, end customers or logisticians: they have to be able to process the data provided by the Shop-Floor-Information-Service.

Stakeholders within Catena-X

  • PURIS, DCM: capacity planning requires a forecast of the products to be delivered,
  • OSim: the Forecast Data from the SIS can serve as input for a OSim-simulation,
  • Traceability: The production tracking aspect allows recalling production data for a specific product, which can be an asset for traceability.

1.2 CONTEXT AND ARCHITECTURE FIT

Higher-level, external influencing factors from the supply chain, such as delays in the logistics chain for supplier parts or short-term order changes, may invalidate a production plan that has already been drawn up. Today, such short-term changes in the general conditions of the production process can often only be taken into consideration indirectly and made through manual corrections. The solution approaches in the Modular Production use case aim to increase the flexibility of production in order to better leverage the existing business potential. For this purpose, services, interface, and data model definitions based on industry standards are offered with the goal of increasing the flexibility and reliability of industrial production. The shop floor is connected to the Catena-X network using the Catena-X standardized connectors. Modular Production will offer a Shop-Floor-Information-Service that supplies information about the production status and planning as needed by other partners in the Catena-X network. The goal is to enable individual production (lot size 1) at the price of series production. In particular, this is to be achieved by automating the orchestration of production resources and planning of production processes as much as possible, thus significantly reducing effort and planning times. A growth in efficiency in the sense of the OEE is achieved by reconfiguring the production in the event of faults to continue operation as well as possible. The increased flexibility creates the space for new business models, such as the interposition of highly prioritized, lucrative orders. As a consequence not only the production is required to be flexible and has to react quickly to changes, it also requires communication of future factory output to the customers. As part of a supply chain the products produced by a Modular Production are part of a bigger product. For this reason, certain parameters are offered to customers by the Production Tracking aspect for the overall documentation of the production process.

Both partners - a customer and a Modular Production - MUST be members of the Catena X network in order to communicate with each other. By registering a Modular Production in advance with the Discovery Service, a customer can find it via a so-called Business Partner Number (BPN). With the help of SSI (Self Sovereign Identity) the correct identity is guaranteed.

1.2.1 Forecasting

The customer uses the GetProductionForecastData call in order to request a production forecast, as specified in section 4.1. The Modular Production generates the required information internally by internal services like a scheduler and answers accordingly by calling ProvideProductionForecastData as specified in section 4.2. For cyclic messages or notifications, the Customer must unsubscribe from the service when the service is no longer required as described in Section 4.3.

SIS Overview

The GetProductionForecastData as well as the ProvideProductionForecastData is using an AAS serialized as a JSON string which is sent through a connector as defined in [CX-0018] (e.g. Tractus-X EDC) mechanism, namely:

  • GetProductionForecastData uses "GetProductionForecast" data model and
  • ProvideProductionForecastData uses "ProvideProductionForecast" data model.

The unsubscribe call has no corresponding data model, as it is a simple HTTP DELETE.

The JSON string is standardized in section 3.1-3.3. The standard only describes the sending and receiving of Shop-Floor-Information-data through a data connector. The object is created and handled by applications of the companies involved, but these applications are not part of the standard.

1.2.2 Production Tracking

The customer uses the GetProductionTrackingData call in order to request production tracking information, as specified in section 4.4. The Modular Production provides the data stored in internal databases and replies accordingly by calling ProvideProductionTrackingData as specified section 4.5.

SIS ProductionTracking Overview

The GetProductionTrackingData as well as the ProvideProductionTrackingData is using an AAS serialized as a JSON string which is sent through connector defined in [CX-0018] (e.g. Tractus-X EDC) mechanisms - namely:

  • GetProductionTrackingData uses "GetProductionTracking" data model and
  • ProvideProductionTrackingData uses "ProvideProductionTracking" data model.

The JSON string is standardized in section 3.4-3.5. The standard only describes the sending and receiving of Shop-Floor-Information-data through a data connector. The object is created and handled by applications of the companies involved, but these applications are not part of the standard.

1.3 CONFORMANCE AND PROOF OF CONFORMITY

1.3.1 For Production Forecasting

All participants and their solutions will need to proof, that they conform to Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Any actor using the Production Forecasting aspect of the Shop-Floor-Information-Service, MUST implement, and follow the following standards:

  • The Shop-Floor-Information-Service Forecasting core business logic – in section 5
  • The Shop-Floor-Information-Service Forecasting standardized API – described section 4
  • The Shop-Floor-Information-Service Forecasting standardized Data Model – described in section 3

In order to prove conformity, the participant needs to provide to the conformity assessment body:

  • An example GetProductionForecast-JSON as created by their solution,
  • An example ProvideProductionForecast-JSON as created by their solution,
  • A proof that their solution can process the example payload JSON as listed below.

In case an assessee wants to get certified WHEN requesting assessment THEN the assessee produces a letter affirming that they adhere to this standard and the letter is signed by person who has full power of attorney

Note that in a future revision of this standard it is planned to offer descriptions of test sets including test cases and test data for validating API implementations.

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

1.3.2 For Production Tracking

All participants and their solutions will need to proof that they conform to Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Any actor using the Shop-Floor-Information-Service, MUST implement, and follow the following standards:

  • The Shop-Floor-Information-Service Tracking core business logic – in section 5
  • The Shop-Floor-Information-Service Tracking standardized API – described section 4
  • The Shop-Floor-Information-Service Tracking standardized Data Model – described in section 3

In order to prove conformity, the participant needs to provide to the conformity assessment body:

  • An example GetProductionTracking-JSON as created by their solution.
  • An example ProvideProductionTracking-JSON as created by their solution.
  • A proof that their solution can process the example payload JSON as listed below.

In case an assessee wants to get certified WHEN requesting assessment THEN the assessee produces a letter affirming that they adhere to this standard and the letter is signed by person who has full power of attorney

Note that in a future revision of this standard it is planned to offer descriptions of test sets including test cases and test data for validating API implementations.

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

1.4 EXAMPLES

Disturbances of the supply chain always have a major impact on the following links in the chain. It is therefore necessary to inform the customers resp. their logistician as soon as possible, as the real date of manufacturing might vary from the one negotiated in the contract. The Shop-Floor-Information-Service therefore gives an update about the scheduled production times to allow a better planning for both the tier n-1 customer as well as for the logistic in-between.

1.4.1 Production Forecast

The following sections are providing examples for the API call as well as for the data models corresponding to the Production Forecast aspects.

1.4.1.1 API

Production Forecast provides three API calls. Examples for each call are listed below.

1.4.1.1.1 Example for GetProductionForecastData

An example JSON string for GetProductionForecast is discussed in section 1.4.1.2. GetProductionForecastData is the request to receive Shop-Floor-Information. It contains the BPNS of the requesting partner, the customerID, which is the internal customerID in the Modular Production management tool and the orderID, for which forecast information is requested. In addition, the requester can select one of the three communication modes: synchronous (the answer will be given immediately), cyclic (the information will be given cyclic with a negotiated cycle, e.g., every day etc.) and notification (changed production date). Each mode requires some additional parameters.

The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined in [CX-0018] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to the endpoint call at the data plane of the Tractus-X EDC, which passes them on to the endpoint at the Modular Production.

The GetProductionForecastData MUST be sent from the requestor of Shop-Floor-Information to the Modular Production using an HTTP GET request.

An example HTTP request is provided below:

GET /get-production-forecast HTTP/1.1
Host: localhost: 3000
Content-Type: application/json
Content-Length: 918
{
"request": {
"orderId": "C95_SLM140_1_W1",
"customerId": "BPNL7588787849VQ",
"deviationOfSchedule": {
"value": 12,
"timeUnit": "unit:secondUnitOfTime"
},
"productionForecastForAll": false,
"version": "2.0.0",
"notificationInterval": {
"value": 12,
"timeUnit": "unit:secondUnitOfTime"
},
"communicationMode": "synchronous"
},
"header": {
"senderBpn": "BPNL6666787765VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
}
}
1.4.1.1.2 Example for ProvideProductionForecastData

An example JSON string for ProvideProductionForecast is discussed in section 1.4.1.2. ProvideProductionForecastData returns the current forecast results in synchronous mode. In the case of the cyclic, the notification and the unsubscribe mode, it contains an immediate confirmation with the corresponding information. In case of a cyclic or notification event the current forecasting information will be sent using the ProvideProductionForecastData mechanism. The endpoint, which is used as the base URL in the asset definition, is executed via a connector as defined in [CX-0018] (e.g. Tractus-X EDC). Since the endpoint execution parameters are sent as path parameters, they are added to the endpoint call at the data plane of the Tractus-X EDC , which forwards them to the endpoint at the producer.

The ProvideProductionForecastData MUST be sent from the Modular Production to the consumer of the Shop-Floor-Information using an HTTP POST request. An example HTTP request is provided below:

POST /provide-production-forecast HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Content-Length: 962
{
"productionForecastResponse" : {
"listOfForecastItems" : [ {
"returnCode" : "ok",
"precisionOfForecast" : {
"value" : 12,
"timeUnit" : "unit:secondUnitOfTime"
},
"reasonsForDelay" : "supplyProblems",
"positionId" : "C95_SLM140_1_W1",
"productionStatus" : "itemReceived",
"productionForecast" : "2023-06-19T21:24:00+07:00",
"forecastDate" : "2023-06-19T21:24:00+07:00"
} ],
"version" : "2.0.0",
"communicationMode" : "synchronous",
"iterationNumber" : 6
},
"header" : {
"senderBpn" : "BPNL7588787849VT",
"relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy" : "2023-06-19T21:24:00+07:00",
"context" : "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0",
"messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn" : "BPNL6666787765VQ",
"sentDateTime" : "2023-06-19T21:24:00+07:00",
"version" : "2.0.0"
}
}
1.4.1.1.3 Example for Unsubscribe

Unsubscribe is used to opt out of receiving information in the case of a cyclic or notification request. The endpoint, which is used as the base URL in the asset definition, is executed via a connector as defined in [CX-0018] (e.g. Tractus-X EDC). Since the endpoint execution parameters are sent as path parameters, they are added to the endpoint call at the data plane of the Tractus-X EDC, which forwards them to the endpoint at the producer.
The Unsubscribe request MUST be sent from the consumer of Shop-Floor-Information to the Modular Production using an HTTP DELETE request.

http://\{internal-server\}/relatedMessageId/00000000-0000-0000-C000-000000000042

The final id value should be copied from the GetProductionForecast. An example HTTP request is seen below:

DELETE /relatedMessageId/00000000-0000-0000-C000-000000000042  HTTP/1.1
Host: {\{internal-server\}}
1.4.1.2 Data Models

In this chapter, examples for the data models of the production Forecast are listed, namely GetProductionForecast and ProvideProductionForecast as well as ShopfloorInformationTypes for common data in form of JSON for reference.

1.4.1.2.1 GetProductionForecast

The following dataset shows an example of a GetProductionForecast which will be sent to the GetProductionForecastData endpoint.
Example request in case of synchronous answers:

{
"header": {
"senderBpn": "BPNL1234567890SE",
"expectedResponseBy": "2023-07-01T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0",
"messageId": "00000000-0000-0000-C000-000000000042",
"recipientBpn": "BPNL0987654321RE",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"request": {
"precisionOfForecast": {
"timeUnit": "day",
"value": 1
},
"offset": {
"timeUnit": "day",
"value": 1
},
"orderId": "0007",
"customerId": "BPNL7588787849VQ",
"deviationOfSchedule": {
"timeUnit": "day",
"value": 7
},
"productionForecastForAll": false,
"version": "2.0.0",
"notificationInterval": {
"timeUnit": "day",
"value": 2
},
"communicationMode": "synchronous"
}
}
1.4.1.2.2 ProvideProductionForecast

The following dataset shows an example for a ProvideProductionForecast which will be sent to the ProvideProductionForecastData endpoint.

{
"header": {
"senderBpn": "BPNL1234567890SE",
"relatedMessageId": "00000000-0000-0000-C000-000000000042",
"expectedResponseBy": "2023-07-02T13:00:00.000+02:00",
"context": "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0",
"messageId": "00000000-0000-0000-C000-000000000046",
"recipientBpn": "BPNL0987654321RE",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"productionForecastResponse": {
"listOfForecastItems": [
{
"returnCode": "ok",
"precisionOfForecast": {
"timeUnit": "day",
"value": 3
},
"reasonsForDelay": "supplyProblems",
"positionId": "0007-3",
"productionStatus": "itemReceived",
"productionForecast": "2023-07-05T14:05:00.000+02:00",
"forecastDate": "2023-07-01T14:05:20.255+02:00"
}
],
"version": "2.0.0",
"communicationMode": "synchronous",
"iterationNumber": 42
}
}
1.4.1.2.3 ShopfloorInformationTypes

In order to use common data in the different models, ShopfloorInformationTypes have also been defined, an example of which is shown below::

{
"timeValue": {
"value": 12,
"timeUnit": "unit:secondUnitOfTime"
},
"communicationMode": "synchronous"
}

1.4.2 Production Tracking

In the following sections examples for the API calls and the data models for production tracking are given.

1.4.2.1 API

Production Tracking provides two API calls. Examples for each call are listed below.

1.4.2.1.1 GetProductionTrackingData

An example JSON string for the GetProductionForecastData can be found in section 1.4.2.2. GetProductionTracking is the request to obtain Shop-Floor-Information regarding the manufacturing steps of a product. The Model itself contains the Catena-X Header Aspect Model (https://github.com/eclipse-tractusx/sldt-semantic-models/tree/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shared.message_header/2.0.0), so that the BPNS of the requesting partner is provided. Within the request, the customerID, which is the internal customerID in the Modular Production management tool, and the identifierNumber, which is used to identify the product for which the production tracking data is requested, are required.

The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined in [CX-0018] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to the endpoint call at the data plane of the Tractus-X EDC, which passes them on to the Modular Production Tractus-X endpoint.

The GetProductionForecastTracking MUST be sent from the requester of Shop-Floor-Information to the Modular Production using an HTTP GET request.

An example of the HTTP request is listed below:

GET /get-production-tracking HTTP/1.1
Host: localhost:3000
Content-Type: application/json
Content-Length: 1007
{
"request" : {
"identifierNumber" : "box-12345678",
"stepIdentifierList" : [ {
"processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterList" : [ {
"processParameterSemanticId" : "0173-1#02-ABK233#001",
"processParameterName" : "Drehmoment_Max"
} ]
} ],
"customerId" : "550e8400-e29b-41d4-a716-446655440000",
"identifierType" : "partInstanceId",
"billOfProcessId" : "box-with-lid-12345678-bill-of-process",
"version" : "1.0.0",
"processReferenceType" : "processStep"
},
"header" : {
"senderBpn" : "BPNL7588787849VQ",
"relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy" : "2023-06-19T21:24:00+07:00",
"context" : "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn" : "BPNL6666787765VQ",
"sentDateTime" : "2023-06-19T21:24:00+07:00",
"version" : "2.0.0"
}
}
1.4.2.1.2 ProvideProductionTrackingData

An example JSON string for the ProvideProductionTracking can be found in section 1.4.2.2. ProvideProductionTrackingData will return a set of manufacturing steps of a product, whereas each of these steps can feature one or multiple process parameters, that were specified with the GetProductionForecastData request. These process step information will be returned so that the requester will receive a single message, containing the ProvideProductionTracking information.

The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined in [CX-0018] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to the endpoint call at the data plane of the Tractus-X EDC , which passes them on to the producer's endpoint.

The ProvideProductionTrackingData MUST be sent from the Modular Production to the consumer of the Shop-Floor-Information using an HTTP POST request. An example HTTP request is provided below:

POST /provide-production-tracking HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Content-Length: 1015
{
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"response": {
"identifierNumber": "box-12345678",
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"identifierType": "partInstanceId",
"version": "1.0.0",
"processStepIdentifierList": [
{
"processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterValueList": [
{
"processParameterName": "Drehmoment_Max",
"semanticId": "0173-1#02-ABK233#001",
"processParameterQuality": "ok",
"processParameterValue": "10"
}
]
}
]
}
}
1.4.2.2 Data Models

This chapter provides examples of the production tracking data models, namely GetProductionTracking and ProvideProductionTracking, for common data in form of JSON for reference.

1.4.2.2.1 GetProductionTracking

The GetProductionTracking data model contains three different cases for a request, namely a partInstanceId, a billOfMaterialId and a billOfProcessId based request, which will be sent to the endpoint GetProductionTrackingData. The cases differ in the various optional fields that become mandatory for the individual cases. The following example illustrates the overall model, however, detailed examples for each of the aforementioned cases are provided in sections 1.4.2.2.1.1 through 1.4.2.2.1.3. In all cases, it is assumed that the required information is common knowledge to both the factory and the customer requesting GetProductionTracking.

{
"request": {
"identifierNumber": "box-12345678",
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"stepIdentifierList": [
{
"processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterList": [
{
"processParameterSemanticId": "0173-1#02-ABK233#001",
"processParameterName": "Drehmoment_Max"
}
],
"capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben",
"billOfMaterialElementId": "Deckel-Bom-123-Schraube",
"partInstanceLevel": "partInstanceId",
"partInstanceId": "Deckel-Serial-123",
"billOfMaterialId": "321-BomIdentifier"
}
],
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"billOfProcessId": "box-with-lid-12345678-bill-of-process",
"identifierType": "partInstanceId",
"version": "1.0.0",
"processReferenceType": "processStep"
},
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
}
}
1.4.2.2.1.1 PartInstanceId based Request

The following shows an example of a partInstanceId based request, where the product and the requested process steps are identified based on on a partInstanceId and a performed capability:

{
"request": {
"identifierNumber": "box-12345678",
"stepIdentifierList": [
{
"processParameterList": [
{
"processParameterSemanticId": "0173-1#02-ABK233#001",
"processParameterName": "Drehmoment_Max"
}
],
"capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben",
"partInstanceLevel": "partInstanceId",
"partInstanceId": "Deckel-Serial-123"
}
],
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"identifierType": "partInstanceId",
"version": "1.0.0",
"processReferenceType": "capability"
},
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
}
}
1.4.2.2.1.2 billOfMaterialId based Request

The following shows an example of the billOfMaterialId based request, where the product and the requested process steps are identified based on on a billOfMaterialId and a performed capability:

{
"request": {
"identifierNumber": "box-12345678",
"stepIdentifierList": [
{
"processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterList": [
{
"processParameterSemanticId": "0173-1#02-ABK233#001",
"processParameterName": "Drehmoment_Max"
}
],
"capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben",
"billOfMaterialElementId": "Deckel-Bom-123-Schraube",
"partInstanceLevel": "bomId",
"billOfMaterialId": "321-BomIdentifier"
}
],
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"identifierType": "bomId",
"version": "1.0.0",
"processReferenceType": "capability"
},
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
}
}
1.4.2.2.1.3 billOfProcessId based Request

The following shows an example of the billOfProcessId based request, where the product can be identified based on a batchId, a partInstanceId or a billOfMaterialId. However, instead of a capability, the process step is identified based on a commonly defined bill of process:

{
"request": {
"identifierNumber": "box-12345678",
"stepIdentifierList": [
{
"processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterList": [
{
"processParameterSemanticId": "0173-1#02-ABK233#001",
"processParameterName": "Drehmoment_Max"
}
]
}
],
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"identifierType": "partInstanceId",
"billOfProcessId": "box-with-lid-12345678-bill-of-process",
"version": "1.0.0",
"processReferenceType": "processStep"
},
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
}
}
1.4.2.2.2 ProvideProductionTracking

The following dataset shows an example for a ProvideProductionTracking which will be sent to the ProvideProductionTrackingData endpoint. Regardless of the case of the request, the response information is always the same.

{
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"response": {
"identifierNumber": "box-12345678",
"catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"identifierType": "partInstanceId",
"version": "1.0.0",
"processStepIdentifierList": [
{
"processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterValueList": [
{
"processParameterName": "Drehmoment_Max",
"semanticId": "0173-1#02-ABK233#001",
"processParameterQuality": "ok",
"processParameterValue": "10"
}
]
}
]
}
}

1.5 TERMINOLOGY

This section is non-normative

NameAbbreviationDescription
AASAsset Administration ShellSpecification to manage and administrate digital representations of assets (concepts, physical device, process, etc.). Used synonymously with the term "Digital Twin".
AMAspect Modela formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect.Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model.Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing).
BPNBusiness Partner NumberBusiness Partner Number
CXCatena-XData ecosystem / data space for the automotive industry.
DCMDemand and Capacity ManagementProduct within Catena-X for shortage identification.
DTDigital TwinDigital representation of an asset (concept, physical device, process, etc.). Realized using the Asset Administration Shell. Used synonymously with the term "Asset Administration Shell".
EDCEclipse Dataspace ConnectorOpen-Source Dataspace Connector Framework to participate in International Data Spaces.
JSONJavaScript Object NotationJson is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects.
MPModular ProductionProduct within Catena-X for shop floor activities
OSimOnline Control and SimulationProduct within Catena-X for Online Simulation along the supply chain
PURISPredictive Unit Real-Time Information SystemProduct within Catena-X for shortage identification.
SAMMSemantic aspect meta modelModelling specification to realize a standardized set of models with strict typing which can be used within the AAS. SAMMs are standardized via the Semantic Layer team and can be looked up via the Semantic Hub.
SISShop-Floor-Information-ServiceService provided by MP in order to give information from the shop floor to customers and third parties
SSISelf Sovereign IdentitySelf Sovereign Identity
 Additional terminology used in this standard can be looked up in the glossary on the association homepage.

2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES

This section is normative

2.1 "Modular Production"

2.1.1 LIST OF STANDALONE STANDARDS

  • CX-0001 EDC Discovery API Version 1.0.2
  • CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2
  • CX-0018 Dataspace Connectivity Version 3.0.0

2.1.2 DATA REQUIRED

No additional data requirements.

2.1.3 ADDITIONAL REQUIREMENTS

Conventions for Use Case Policy in context data exchange:

In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards.

For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to

  • the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines.
  • the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming.

Additional Details regarding Access Policies:

A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain participants, the Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, the Data Provider may apply Access Policies to restrict access to a particular data offer for only one participant identified by a specific business partner number.

Additional Details regarding Usage Policies:

In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules:

  • Use Case Framework (“FrameworkAgreement”)
  • at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository.

Additionally, respective usage policies MAY include the following policy rule:

  • Reference Contract (“ContractReference”).

Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository.

2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs

This version of the document does not define any requirements for standardized integration and governance of digital twins.

3 ASPECT MODELS

This section is normative

3.1 ASPECT MODEL "GetProductionForecast"

3.1.1 INTRODUCTION

The GetProductionForecast MUST be sent by the customer or a third party to the Modular Production via an HTTP request. The data format described here MUST be followed. The GetProductionForecast data model MUST be implemented by all participants who wish to use the Shop-Floor-Information-Service as a Modular Production, a customer or a participating third party. For GetProductionForecast the requester MUST either select the "synchronous", "cyclic" or "notification" communication mode. Companies which use the Shop-Floor-Information-Service as a customer or third party MUST be able to send GetProductionForecastData requests. Companies which use the Shop-Floor-Information-Service as a Modular Production MUST be able to receive GetProductionForecastData requests.

3.1.2 SPECIFICATIONS ARTIFACTS

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

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

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

3.1.3 LICENSE

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

3.1.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

    urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0

This identifier MUST be used by the data provider to define the semantics of the data being transferred.

3.1.5 FORMATS OF SEMANTIC MODEL

3.1.5.1 RDF TURTLE

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

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shopfloor_information.get_production_forecast/2.0.0/GetProductionForecast.ttl

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

3.1.5.2 JSON SCHEMA

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

3.1.5.3 AASX

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

3.1.5.4 SEMANTIC MODEL

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

The GetProductionForecast model is described in detail in the table below:

FieldLevelREQUIREDPurposeData TypeExample Value
senderBpnCX-headermandatoryidentification of the senderstringBPNL1234567890SE
recipientBpnCX-headermandatoryidentification of the recipientstringBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-01T21:24:00+07:00
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BE urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
versionCX-headermandatoryof Meta model used for compatibilitystring2.0.0
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
versionSIS-Payloadmandatoryversion of the datamodelstring2.0.0
customerIdSIS-PayloadmandatoryThe internal ID of the customer of the Modular Production in order to identify the customer in the databasestringVLhpfQGTMDYpsBZxvfBoeygjb
orderIdSIS-PayloadmandatoryThe orderID communicated between the Modular Production and the customerstring0007
communicationModeSIS-PayloadmandatoryEnum describing which communication mode is used for data exchange resp. the mode of the response: synchronous, cyclic or notificationenumsynchronous
productionForecast4AllSIS-Payloadmandatoryif true, the forecast for the entire order will be sent (more precise: latest production date of all suborders ) instead of splitting it in the subordersbooltrue
offsetSIS-Payloadmandatorytimespan to activating of cyclic and notification; for immediate response it should be "0"TimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 1 }
notificationIntervalSIS-Payloadoptional if [cyclic] = mandatoryin case of cyclic notification it is giving the period of the notification cycles if (communicationMode == [cyclic]) => mandatoryTimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 2 }
deviationOfScheduleSIS-Payloadoptional if [notification] = mandatoryin case of notification a tolerance will be defined for triggering a new notification to avoid too many notifications with smaa deviations in the forecasting date if (communicationMode == [notification]) => mandatoryTimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 7 }
precisionOfForecastSIS-PayloadoptionalRequested precision of the forecasting date default, the production defines the date in case of a requested precisionOfForecast, the Modular Production delivers with the required precision if the precision is not possible, an error code is send and the forecast will be the best possible precisionTimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 1 }
  • The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0.
  • The API GetProductionForecastData 4.1 call MUST use the GetProductionForecast data model.
  • Communication Mode MUST be one of the following items: synchronous, cyclic and notification.
  • EnumTimeUnits MUST be one of the following items: seconds, minutes, hour, day, week, month, year.

3.2 ASPECT MODEL "ProvideProductionForecast"

3.2.1 INTRODUCTION

Companies which use the Shop-Floor-Information-Service as a customer or third party MUST be able to receive ProvideProductionForecast information. Companies which use the Shop-Floor-Information-Service as a factory MUST be able to send ProvideProductionForecast information.

3.2.2 SPECIFICATIONS ARTIFACTS

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

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

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

3.2.3 LICENSE

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

3.2.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier:

    urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0

3.2.5 FORMATS OF SEMANTIC MODEL

3.2.5.1 RDF TURTLE

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

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shopfloor_information.provide_production_forecast/2.0.0/ProvideProductionForecast.ttl

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

3.2.5.2 JSON SCHEMA

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

3.2.5.3 AASX

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

3.2.5.4 SEMANTIC MODEL

The ProvideProductionForecastData model is described in detail in the following table:

FieldLevelREQUIREDPurposeDatatypeExample Value
versionCX-headermandatoryof Meta model used for compatibilitystring2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BEurn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
senderBpnCX-headermandatoryidentification of the senderstringBPNL1234567890SE
recipientBpnCX-headermandatoryidentification of the recipientstringBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
versionSIS-Payloadmandatoryversion of the datamodelstring2.0.0
iterationNoSIS-Payloadoptionalin case of cyclic or notification mode this field is used to count the iterations to keep them in the correct orderint42
communicationModeSIS-PayloadmandatoryEnum describing if synchronous, cyclic or notification is used for data exchangeenumsynchronous
ListOfForecastItemsSIS-Payloadmandatorylist containing the items corresponding to the order of this requestList of Forecast Items
ForecastItem*SIS-Payload
positionIdSIS-Payloadmandatoryfield referring to the ID of this item in the order list, e.g. item number in case of productionForecastForAll =true : provide order ID instead of position IDUUID / string0007-3
productionForecastSIS-Payloadmandatorydate of finalizing the production, this does not cover additional internal activities e.g. logisticdatetime2023-07-05T14:05:00.000+02:00
precisionOfForecastSIS-Payloadmandatoryprecision of the forecast in form of an interval e.g. +-3days, the precision either matches to the required precision of the request or the maximal possible precision.TimeValue [EnumTimeUnits, uint ]{ "timeUnit": "day", "value": 3 },
productionStatusSIS-Payloadmandatory/optstatus of the productionenum <ProductionStatus>itemReceived
forecastDateSIS-Payloadmandatorydate of determination the forecasting statusdatetime2023-07-01T14:05:20.255+02:00
reasonForDelaySIS-Payloadmandatoryin case of a delay a possible explanationenumsupplyProblems
  • The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0.
  • The API ProvideProductionForecastData call in section 4.2 MUST use the ProvideProductionForecast data model.
  • Communication Mode MUST be one of the following items: synchronous, cyclic and notification.
  • EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, unit:week, unit:month, unit:year.
  • ProductionStatus MUST be one of the following items: itemReceived, itemPlanned, itemInProduction, itemCompleted, statusUndefined, ordered following the figure below.

Production States

  • reasonsForDelay MUST be one of the following items: supplyProblems, internalProblems, otherCircumstances, noInformationAvailable.

3.3 ASPECT MODEL "ShopfloorInformationTypes "

The ShopfloorInformationTypes MUST be used for all parties using ProvideProductionForecastData or GetProductionForecastData information.

3.3.1 INTRODUCTION

The ShopfloorInformationTypes are a collection of commonly used data models of ProvideProductionForecastData or GetProductionForecastData.

3.3.2 SPECIFICATIONS ARTIFACTS

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

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

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

3.3.3 LICENSE

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

3.3.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier:

    urn:samm:io.catenax.shared.shopfloor_information_types:2.0.0

This identifier MUST be used by the data provider to define the semantics of the data being transferred.

3.3.5 FORMATS OF SEMANTIC MODEL

3.3.5.1 RDF TURTLE

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

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shared.shopfloor_information_types/2.0.0/ShopfloorInformationTypes.ttl

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

3.3.5.2 JSON SCHEMA

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

3.3.5.3 AASX

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

3.3.5.4 SEMANTIC MODEL

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

The ShopfloorInformationTypes model is described in detail in the following table:

FieldPurposeDatatypeExample Value
communicationModeEnum describing if synchronous, cyclic or notification is used for data exchangeenumsynchronous
timeValuedataFormat for storing timeValuesTimeValue [EnumTimeUnits, uint ]{ "timeUnit": "day", "value": 3 }

Communication Mode MUST be one of the following items: synchronous, cyclic and notification.

EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, unit:week, unit:month, unit:year.

3.4 ASPECT MODEL "GetProductionTracking"

The GetProductionTracking data model MUST be used for all parties using GetProductionTrackingData.

3.4.1 INTRODUCTION

3.4.2 SPECIFICATIONS ARTIFACTS

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

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

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

3.4.3 LICENSE

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

3.4.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0

This identifier MUST be used by the data provider to define the semantics of the data being transferred.

3.4.5 FORMATS OF SEMANTIC MODEL

3.4.5.1 RDF TURTLE

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

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shopfloor_information.get_production_tracking/1.0.0/GetProductionTracking.ttl

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

3.4.5.2 JSON SCHEMA

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

3.4.5.3 AASX

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

3.4.5.4 SEMANTIC MODEL

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

The GetProductionTracking model is described in detail in the following table:

FieldLevelRequiredPurposeDatatypeExample Value
header
senderBpnCX-Headermandatoryof Meta Model used for compatibilityBpnlCharacteristicBPNL1234567890SE
versionCX-headermandatoryof Meta model used for compatibilityVersionCharacteristic2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BE urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
recipientBpnCX-headermandatoryidentification of the recipientBpnlCharacteristicBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
request
versionSIS-Payloadmandatoryof Meta model used for compatibilityVersionCharacteristic1.0.0
customerIdSIS-Payloadmandatoryinternal customer numberstring550e8400-e29b-41d4-a716-446655440000
catenaXIdSIS-Payloadoptionalidentifier of a product that is registered in a catena-x digital twin registryuuidurn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379
identifierTypeSIS-Payloadmandatoryspecifies the kind of the identifierNumberenum : [partInstanceId, batchId, billOfMaterialId]partInstanceId
identifierNumberSIS-Payloadmandatoryidentifier of a productstringbox-12345678
processReferenceTypeSIS-Payloadmandatorydetermines whether a process step is identified with a capability or a processStepIdentifier of a billOfProcessstringprocessStep
billOfProcessIdSIS-Payloadoptionalidentifier of a bill of process known by both partnersstringbox-with-lid-12345678-bill-of-process
stepIdentifierListSIS-Payloadmandatorylists all process steps from which parameters are requestedlist
capabilityIdSIS-Payloadoptionalidentifier of a capabilitystringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben
partInstanceLevelSIS-Payloadoptionaldetermines whether a sub-product is identified based on a bill of material or a partInstanceIdenum : [partInstanceId, billOfMaterialId]partInstanceId
billOfMaterialIdSIS-Payloadoptionalidentifier of a bill of materialstring321-BomIdentifier
billOfMaterialElementIdSIS-Payloadoptionalidentifies a concrete element of the bill of material referenced with the billOfMaterialIdstringDeckel-Bom-123-Schraube
partInstanceIdSIS-PayloadoptionalpartInstanceId to identify a sub-product of a productstringDeckel-Serial-123
processStepIdSIS-Payloadoptionalidentifier of a process step referenced in the billOfProcessIdstringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01
processParameterListSIS-PayloadmandatoryLists all process Parameter requested from a process steplist
processParameterNameSIS-Payloadmandatoryname of a requested process parameterstringDrehmoment_Max
processParameterSemanticIdSIS-Payloadmandatorylink to a semantic that characterizes the type of the process parameterstring0173-1#02-ABK233#001
  • The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0.
  • IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId
  • processReferenceType Mode MUST be one of the following items: processStep, capability
  • partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId
  • partInstanceId COULD be a serial number or a different unique identifier for a specific part of an asset

3.5 ASPECT MODEL "ProvideProductionTracking"

The ProvideProductionTracking data model MUST be used for all parties using ProvideProductionForecastData.

3.5.1 INTRODUCTION

The ProvideProductionTracking are a collection of commonly used data models of ProvideProductionTrackingData.

3.5.2 SPECIFICATIONS ARTIFACTS

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

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

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

3.5.3 LICENSE

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

3.5.4 IDENTIFIER OF SEMANTIC MODEL

The semantic model has the unique identifier

urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0

This identifier MUST be used by the data provider to define the semantics of the data being transferred.

3.5.5 FORMATS OF SEMANTIC MODEL

3.5.5.1 RDF TURTLE

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

https://github.com/eclipse-tractusx/sldt-semantic-models/blob/4d239fc5709f71f39c3cf13581b5bcf960905157/io.catenax.shopfloor_information.provide_production_tracking/1.0.0/ProvideProductionTracking.ttl

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

3.5.5.2 JSON SCHEMA

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

3.5.5.3 AASX

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

3.5.5.4 SEMANTIC MODEL

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

The ProvideProductionTracking data model is described in detail in the following table:

FieldLevelRequiredPurposeDatatypeExample Value
header
senderBpnCX-Headermandatoryof Meta Model used for compatibilityBpnlCharacteristicBPNL1234567890SE
versionCX-headermandatoryof Meta model used for compatibilityVersionCharacteristic2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BEurn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
recipientBpnCX-headermandatoryidentification of the recipientBpnlCharacteristicBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
response
versionSIS-Payloadmandatoryof Meta model used for compatibilityVersionCharacteristic1.0.0
catenaXIdSIS-Payloadoptionalidentifier of a product that is registered in a catena-x digital twin registryuuidurn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379
identifierTypeSIS-Payloadmandatoryspecifies the kind of the identifierNumberenumpartInstanceId
identifierNumberSIS-Payloadmandatoryidentifier of a productstringbox-12345678
processStepIdentifierListSIS-PayloadmandatoryLists all process steps for which parameters are providedlist
processStepIdSIS-Payloadoptionalidentifier of a process step referenced in the billOfProcessIdstringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01
processParameterValueListSIS-PayloadmandatoryLists all process Parameter provided for a process steplist
processParameterNameSIS-Payloadmandatoryname of a requested process parameterstringDrehmoment_Max
processParameterSemanticIdSIS-Payloadmandatorylink to a semantic that characterizes the type of the process parameterstring0173-1#02-ABK233#001
processParameterValueSIS-Payloadmandatorythe concrete value of a process parameterstring10
processParameterQualitySIS-Payloadmandatoryindicates the quality of the parameters value measurementenumnoValue
  • The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0.
  • IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId
  • processReferenceType Mode MUST be one of the following items: processStep, capability
  • partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId

4 APPLICATION PROGRAMMING INTERFACES

This section is normative

4.1 "GetProductionForecastData" API

This introduction holds for 4.1-4.3:

The GetProductionForecastData contains the request for forecast data sent by a Modular Production partner to a customer or a third party at the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a customer or third party MUST be able to send GetProductionForecastData. All participants using the Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process GetProductionForecastData.

The following diagram shows the complete communication between the partners in an abstract way. It takes place in different phases:

  1. Negotiation between the connector as in [CX-0018] (e.g. Tractus-X EDC),
  2. Data connector of the partners using the needed policies,
  3. GetProductionForecastData(...) - the call of the customer,
  4. get the desired information via ProvideProductionForecastData(...) - transferred by Modular Production (synchronous, cyclic or notification-like),
  5. Unsubscribe from the "GetProductionForecastData" service to stop receiving further information.

Production Tracking

The two boxes in the middle represent the data connector like Tractus-X EDC of the partners. The communication between the respective connectors is transparent to the user (shaded). The transmission of the data for the request, as well as the response to the ProductionForecast is transmitted via the payload of the message. The immediate response (http response) does not contain any technical information. The left side represents the customer with his different requests. On the right is the Modular Production with a scheduler that generates the requested answers.

4.1.1 PRECONDITIONS AND DEPENDENCIES

The GetProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.1.2 API SPECIFICATION

4.1.2.1 API Endpoints & resources

When sending a request to the GetProductionForecastDataEndpoint, the body MUST be composed out of two information objects: a header and content. Together they form the HTTP body that MUST be formatted as JSON.

The elements of the message are described in the following table:

FieldLevelREQUIREDPurposeData TypeExample Value
senderBpnCX-headermandatoryidentification of the senderstringBPNL1234567890SE
recipientBpnCX-headermandatoryidentification of the recipientstringBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-01T21:24:00+07:00
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BE urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
versionCX-headermandatoryof Meta model used for compatibilitystring2.0.0
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
versionSIS-Payloadmandatoryversion of the datamodelstring2.0.0
customerIdSIS-PayloadmandatoryThe internal ID of the customer of the Modular Production in order to identify the customer in the databasestringVLhpfQGTMDYpsBZxvfBoeygjb
orderIdSIS-PayloadmandatoryThe orderID communicated between the Modular Production and the customerstring0007
communicationModeSIS-PayloadmandatoryEnum describing which communication mode is used for data exchange resp. the mode of the response: synchronous, cyclic or notificationenumsynchronous
productionForecast4AllSIS-Payloadmandatoryif true, the forecast for the entire order will be sent (more precise: latest production date of all suborders ) instead of splitting it in the subordersbooltrue
offsetSIS-Payloadmandatorytimespan to activating of cyclic and notification; for immediate response it should be "0"TimeValue [EnumTimeUnits, uint ]{ "timeUnit": "day", "value": 1 }
notificationIntervalSIS-Payloadoptional if [cyclic] = mandatoryin case of cyclic notification it is giving the period of the notification cycles if (communicationMode == [cyclic]) => mandatoryTimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 2 }
deviationOfScheduleSIS-Payloadoptional if [notification] = mandatoryin case of notification a tolerance will be defined for triggering a new notification to avoid too many notifications with smaa deviations in the forecasting date if (communicationMode == [notification]) => mandatoryTimeValue [EnumTimeUnits, uint ]{ "timeUnit": "day", "value": 7 }
precisionOfForecastSIS-PayloadoptionalRequested precision of the forecasting date default, the production defines the date in case of a requested precisionOfForecast, the Modular Production delivers with the required precision if the precision is not possible, an error code is send and the forecast will be the best possible precisionTimeValue [EnumTimeUnits, uint ]{"timeUnit": "day", "value": 1 }

The following JSON object gives an example of a valid data model:

{
"header": {
"senderBpn": "BPNL1234567890SE",
"expectedResponseBy": "2023-07-01T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0",
"messageId": "00000000-0000-0000-C000-000000000046",
"recipientBpn": "BPNL0987654321RE",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"request": {
"precisionOfForecast": {
"timeUnit": "day",
"value": 1
},
"offset": {
"timeUnit": "day",
"value": 1
},
"orderId": "0007",
"customerId": "BPNL7588787849VQ",
"deviationOfSchedule": {
"timeUnit": "day",
"value": 7
},
"productionForecastForAll": false,
"version": "2.0.0",
"notificationInterval": {
"timeUnit": "day",
"value": 2
},
"communicationMode": "synchronous"
}
}

Available Data Types:

  • The API GetProductionForecastData call MUST use the GetProductionForecast data model defined in section 3.1.
  • The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the endpoints is provided in the corresponding sections of Section 3.1.
  • Communication Mode MUST be one of the following items: synchronous, cyclic and notification.
  • EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, unit:week, unit:month, unit:year.

4.1.2.2 DATA ASSET STRUCTURE

The HTTP GET endpoint introduced in chapter 4.1.1 MUST NOT be called from a partner directly. Rather, it MUST be called via the communication defined in [CX-0018]. Therefore, the endpoint MUST be offered as an Data Asset.

  • The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique.
  • The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains.
  • The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to identify if there have been updates on an asset definition.
  • The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where the function “GetProductionForecastData” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use connectors compliant to [CX-0018] as a reverse proxy by adding parameters to the URL.

The API version described in this standard document MUST be published in the property <https://w3id.org/catenax/ontology/common#version> as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer.

Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions.

An example Tractus-X Data Asset definition with corresponding access / usage policies and a contract definition is shown below. Note: Expressions in double curly braces {{}} must be substituted with a corresponding value.

Asset definition:

{
"@context": {
"": "[https://w3id.org//v0.0.1/ns/](https://w3id.org/edc/v0.0.1/ns/)",
"cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)",
"cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)",
"dct": "<https://purl.org/dc/terms/>"
},
"@id": "sis-request-production-forecast-01",
"properties": {
"description": "Request Production Forecast Asset",
"privateProperties": {},
"cx-common:version": "2.0"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "{SIS_REQUEST_PRODUCTION_FORECAST_ENDPOINT}}",
"method": "GET",
"proxyPath": "true",
"contentType": "application/json"
}
}

Access and Usage Policy definition:

{
"@context": {
"@vocab": "[https://w3id.org//v0.0.1/ns/](https://w3id.org/edc/v0.0.1/ns/)"
},
"@id": "sis-request-production-forecast-01-policy",
"policy": {
"@context": [
"<https://www.w3.org/ns/odrl.jsonld>",
{
"cx-policy": "<https://w3id.org/catenax/policy/v1.0.0/>"
}
],
"@type": "Policy",
"profile": "cx-policy:profile2405",
"permission": [
{
"action": "use",
"constraint": {
"or": [
{
"leftOperand": "BusinessPartnerNumber",
"operator": "eq",
"rightOperand": "{{POLICY_BPN}}"
}
]
}
}
]
}
}

Contract definition:

{
"@context": {},
"@id": "sis-request-production-forecast-01-contract",
"@type": "ContractDefinition",
"accessPolicyId": "sis-request-production-forecast-01-policy",
"contractPolicyId": "sis-request-production-forecast-01-policy",
"assetsSelector" : {
"@type" : "CriterionDto",
"operandLeft": "https://w3id.org//v0.0.1/ns/id",
"operator": "=",
"operandRight": "sis-request-production-forecast-01"
}
}

4.1.2.3 ERROR HANDLING

Every API endpoint defined in Chapter 4.1.2.11 MUST respond to incoming requests with HTTP status codes as described in [RFC9110]. The status codes for each endpoint are defined in the following sections.

Status CodeDescriptionUsage
200OKThe request has succeeded.
201OK, Precision not possibleThe request has succeeded. Precision is not possible, the default precision will be used
400Bad requestThe server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401UnauthorizedAlthough the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource.
420Unknown BPNSThe BPNS which is given as parameter is not registered in the data provider database as a direct partner.
421Invalid CustomerIdThe customerID unknown or invalid
422Invalid OrderIdThe orderID not found or invalid
423Invalid Notification IntervalThe data field Notification interval is not set with a proper value or missing
424Invalid DeviationThe data field Deviation is not set with a proper value or missing
425ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource.
426incomplete Request

4.2 "ProvideProductionForecastData" API

The ProvideProductionForecastData API sends the forecast data from a Modular Production to the customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a Modular Production MUST be able to send the ProvideProductionForecastData. All participants using the Shop-Floor-Information-Service in the role of a customer or additional third party MUST be able to receive and process the ProvideProductionForecastData.

4.2.1 PRECONDITIONS AND DEPENDENCIES

The ProvideProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.2.2 API SPECIFICATION

4.2.2.1 API Endpoints & resources

When sending a request to the ProvideProductionForecastData Endpoint, the body MUST be composed out of two information objects: a header and content. Together they form the HTTP body that MUST be formatted as JSON Request Header.

Note: This is not the HTTP Header but rather part of the HTTP Body.

FieldLevelREQUIREDPurposeDatatypeExample Value
versionCX-headermandatoryof Meta model used for compatibilitystring2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BEurn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
senderBpnCX-headermandatoryidentification of the senderstringBPNL1234567890SE
recipientBpnCX-headermandatoryidentification of the recipientstringBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
versionSIS-Payloadmandatoryversion of the datamodelstring2.0.0
iterationNoSIS-Payloadoptionalin case of cyclic or notification mode this field is used to count the iterations to keep them in the correct orderint42
communicationModeSIS-PayloadmandatoryEnum describing if synchronous, cyclic or notification is used for data exchangeenumsynchronous
ListOfForecastItemsSIS-Payloadmandatorylist containing the items corresponding to the order of this requestList of Forecast Items
ForecastItem*SIS-Payload
positionIdSIS-Payloadmandatoryfield referring to the ID of this item in the order list, e.g. item number in case of productionForecastForAll =true : provide order ID instead of position IDUUID / string0007-3
productionForecastSIS-Payloadmandatorydate of finalizing the production, this does not cover additional internal activities e.g. logisticdatetime2023-07-05T14:05:00.000+02:00
precisionOfForecastSIS-Payloadmandatoryprecision of the forecast in form of an interval e.g. +-3days, the precision either matches to the required precision of the request or the maximal possible precision.TimeValue [EnumTimeUnits, uint ]{ "timeUnit": "day", "value": 3 },
productionStatusSIS-Payloadmandatory/optstatus of the productionenum <ProductionStatus>itemReceived
forecastDateSIS-Payloadmandatorydate of determination the forecasting statusdatetime2023-07-01T14:05:20.255+02:00
reasonForDelaySIS-Payloadmandatoryin case of a delay a possible explanationenumsupplyProblems

The following JSON object provides an example of a valid header and payload:

{
"header": {
"senderBpn": "BPNL7588787849VQ",
"relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy": "2023-06-19T21:24:00+07:00",
"context": "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0",
"messageId": "3b405-e214-47a1-b0c2-1d831cdd9ba9",
"recipientBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "2.0.0"
},
"productionForecastResponse": {
"listOfForecastItems": [
{
"returnCode": "ok",
"precisionOfForecast": {
"value": 12,
"timeUnit": "unit:secondUnitOfTime"
},
"reasonsForDelay": "supplyProblems",
"positionId": "00000000-0000-0000-C000-000000000046",
"productionStatus": "itemReceived",
"productionForecast": "2023-06-19T21:24:00+07:00",
"forecastDate": "2023-06-19T21:24:00+07:00"
}
],
"version": "2.0.0",
"communicationMode": "synchronous",
"iterationNumber": 6
}
}

Available Data Types:

  • The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the endpoints is provided in the corresponding sections of Section 3.2.
  • The API ProvideProductionForecastData call MUST use the ProvideProductionForecast data model defined in section 3.2.
  • Communication Mode MUST be one of the following items: synchronous, cyclic and notification.
  • EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, unit:week, unit:month, unit:year.
  • ProductionStatus MUST be one of the following items: itemReceived, itemPlanned, itemInProduction,itemCompleted, statusUndefined.
  • reasonsForDelay MUST be one of the following items: supplyProblems, internalProblems, otherCircumstances, noInformationAvailable.

4.2.2.2 DATA ASSET STRUCTURE

The HTTP POST endpoint introduced in chapter 4.2.1 MUST NOT be called from a partner directly. Rather, it MUST be called via a data connection compliant to [CX-0018] communication. Therefore, the endpoint MUST be offered as an Data Asset.

  • The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique.
  • The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains.
  • The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to identify if there have been updates on an asset definition.
  • The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where the function “ProvideProductionForecast” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use a connector compliant with [CX-0018] as a reverse proxy by adding parameters to the URL.

An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces {{}} must be substituted with a corresponding value.

Asset definition:

{
"@context": {
"edc": "<https://w3id.org/edc/v0.0.1/ns/>",
"cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)",
"cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)",
"dct": "<https://purl.org/dc/terms/>"
},
"@id": "sis-provide-production-forecast-01",
"properties": {
"description": "Provide Production Forecast Asset",
"privateProperties": {},
"cx-common:version": "2.0"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "{SIS_PROVIDE_PRODUCTION_FORECAST_ENDPOINT}}",
"method": "POST",
"proxyPath": "true",
"contentType": "application/json"
}
}

Access and Usage Policy definition:


{
"@context": {
"@vocab": "<https://w3id.org/edc/v0.0.1/ns/>"
},
"@id": "sis-provide-production-forecast-01-policy",
"policy": {
"@context": [
"<https://www.w3.org/ns/odrl.jsonld>",
{
"cx-policy": "<https://w3id.org/catenax/policy/v1.0.0/>"
}
],
"@type": "Policy",
"profile": "cx-policy:profile2405",
"permission": [
{
"action": "use",
"constraint": {
"or": [
{
"leftOperand": "BusinessPartnerNumber",
"operator": "eq",
"rightOperand": "{{POLICY_BPN}}"
}
]
}
}
]
}
}

Contract definition:

{
"@context": {},
"@id": "sis-provide-production-forecast-01-contract",
"@type": "ContractDefinition",
"accessPolicyId": "sis-provide-production-forecast-01-policy",
"contractPolicyId": "sis-provide-production-forecast-01-policy",
"assetsSelector" : {
"@type" : "CriterionDto",
"operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
"operator": "=",
"operandRight": "sis-provide-production-forecast-01"
}
}

4.3 "Unsubscribe" API

The Unsubscribe API contains the request to stop transferring forecasting data which is sent from a Modular Production to a customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a customer or third party MUST be able to send the unsubscribe request. All participants using the Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process the unsubscribe request.

4.3.1 PRECONDITIONS AND DEPENDENCIES

4.3.2 API SPECIFICATION

The GetProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.3.2.1 API Endpoints & resources

The Unsubscribe API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.3.2.2 DATA ASSET STRUCTURE

The HTTP DELETE endpoint introduced in chapter 4.3 MUST NOT be called from a partner directly. Rather, it MUST be called via a connector conformant to [CX-0018] like Tractus-X EDC communication. Therefore, the endpoint MUST be offered as an Data Asset.

  • The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique.
  • The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains.
  • The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to identify if there have been updates on an asset definition.
  • The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where the function “unsubscribe” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the data connectorcompliant to CS-0018 as a reverse proxy by adding parameters to the URL.

An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces {{}} must be substituted with a corresponding value.

Asset definition:

{
"@context": {
"edc": "<https://w3id.org/edc/v0.0.1/ns/>",
"cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)",
"cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)",
"dct": "<https://purl.org/dc/terms/>"
},
"@id": "sis-unsubscribe-production-forecast-01",
"properties": {
"description": "Unsubscribe Production Forecast Asset",
"privateProperties": {},
"cx-common:version": "2.0"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "{SIS_UNSUBSCRIBE_PRODUCTION_FORECAST_ENDPOINT}}",
"method": "DELETE",
"proxyPath": "true",
"contentType": "application/json"
}
}

Access and Usage Policy definition:

{
"@context": {
"@vocab": "<https://w3id.org/edc/v0.0.1/ns/>"
},
"@id": "sis-unsubscribe-production-forecast-01-policy",
"policy": {
"@context": [
"<https://www.w3.org/ns/odrl.jsonld>",
{
"cx-policy": "<https://w3id.org/catenax/policy/v1.0.0/>"
}
],
"@type": "Policy",
"profile": "cx-policy:profile2405",
"permission": [
{
"action": "use",
"constraint": {
"or": [
{
"leftOperand": "BusinessPartnerNumber",
"operator": "eq",
"rightOperand": "{{POLICY_BPN}}"
}
]
}
}
]
}
}

Contract definition:

{
"@context": {},
"@id": "sis-unsubscribe-production-forecast-01-contract",
"@type": "ContractDefinition",
"accessPolicyId": "sis-unsubscribe-production-forecast-01-policy",
"contractPolicyId": "sis-unsubscribe-production-forecast-01-policy",
"assetsSelector" : {
"@type" : "CriterionDto",
"operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
"operator": "=",
"operandRight": "sis-unsubscribe-production-forecast-01"
}
}

4.3.2.3 ERROR HANDLING

Every API endpoint defined in Chapter 4.3.1 MUST respond to incoming requests with HTTP status codes as described in [RFC9110]. The status codes for each endpoint are defined in the following sections.

Status CodeDescriptionUsage
200OKThe request has succeeded. Unsubscribe was successful
400Bad RequestThe server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401UnauthorizedAlthough the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource.
420Unknown relatedMessageIDThe combination of relatedMessageId and BPNS does not fit

4.4 "GetProductionTrackingData" API

This introduction holds for 4.4-4.5:

The GetProductionTrackingData contains the request for tracking data which is sent from a Modular Production partner to a customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a customer or third party MUST be able to send the GetProductionTrackingData . All participants using the Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process the GetProductionTrackingData .

The following diagram shows the complete communication between the partners in a abstract way. It takes place in different phases:

  1. Negotiation between the data connectors of the partners like Tractus-X EDC using the needed policies.
  2. GetProductionTrackingData(...) - the call of the customer.
  3. get the desired information via ProvideProductionTrackingData(...) - transfered by Modular Production.

SIS Tracking

4.4.1 PRECONDITIONS AND DEPENDENCIES

4.4.2 API SPECIFICATION

The GetProductionTrackingData API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.4.2.1 API Endpoints & resources

When sending a request to the GetProductionTrackingData Endpoint, the body MUST be composed out of two information objects: a header and a content. Together they form the HTTP body that MUST be formatted as JSON Request Header.

FieldLevelRequiredPurposeDatatypeExample Value
header
senderBpnCX-Headermandatoryof Meta Model used for compatibilityBpnlCharacteristicBPNL1234567890SE
versionCX-headermandatoryof Meta model used for compatibilityVersionCharacteristic2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BE urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
recipientBpnCX-headermandatoryidentification of the recipientBpnlCharacteristicBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
request
versionSIS-Payloadmandatoryof Meta model used for compatibilityVersionCharacteristic1.0.0
customerIdSIS-Payloadmandatoryinternal customer numberstring550e8400-e29b-41d4-a716-446655440000
catenaXIdSIS-Payloadoptionalidentifier of a product that is registered in a catena-x digital twin registryuuidurn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379
identifierTypeSIS-Payloadmandatoryspecifies the kind of the identifierNumberenumpartInstanceId
identifierNumberSIS-Payloadmandatoryidentifier of a productstringbox-12345678
processReferenceTypeSIS-Payloadmandatorydetermines whether a process step is identified with a capability or a processStepIdentifier of a billOfProcessstringprocessStep
billOfProcessIdSIS-Payloadoptionalidentifier of a bill of process known by both partnersstringbox-with-lid-12345678-bill-of-process
stepIdentifierListSIS-Payloadmandatorylists all process steps from which parameters are requestedlist
capabilityIdSIS-Payloadoptionalidentifier of a capabilitystringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben
partInstanceLevelSIS-Payloadoptionaldetermines whether a sub-product is identified based on a bill of material or a partInstanceIdenumpartInstanceId
billOfMaterialIdSIS-Payloadoptionalidentifier of a bill of materialstring321-BomIdentifier
billOfMaterialElementIdSIS-Payloadoptionalidentifies a concrete element of the bill of material referenced with the billOfMaterialIdstringDeckel-Bom-123-Schraube
partInstanceIdSIS-PayloadoptionalpartInstanceId to identify a sub-product of a productstringDeckel-Serial-123
processStepIdSIS-Payloadoptionalidentifier of a process step referenced in the billOfProcessIdstringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01
processParameterListSIS-PayloadmandatoryLists all process Parameter requested from a process steplist
processParameterNameSIS-Payloadmandatoryname of a requested process parameterstringDrehmoment_Max
processParameterSemanticIdSIS-Payloadmandatorylink to a semantic that characterizes the type of the process parameterstring0173-1#02-ABK233#001

The following JSON object gives an example of a valid data model:

{
"request" : {
"identifierNumber" : "box-12345678",
"stepIdentifierList" : [ {
"processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterList" : [ {
"processParameterSemanticId" : "0173-1#02-ABK233#001",
"processParameterName" : "Drehmoment_Max"
} ]
} ],
"customerId" : "550e8400-e29b-41d4-a716-446655440000",
"identifierType" : "partInstanceId",
"billOfProcessId" : "box-with-lid-12345678-bill-of-process",
"version" : "1.0.0",
"processReferenceType" : "processStep"
},
"header" : {
"senderBpn" : "BPNL7588787849VQ",
"relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy" : "2023-06-19T21:24:00+07:00",
"context" : "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0",
"messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn" : "BPNL6666787765VQ",
"sentDateTime" : "2023-06-19T21:24:00+07:00",
"version" : "2.0.0"
}
}

Available Data Types:

  • The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the endpoints is provided in the corresponding sections of Section 3.4.
  • The API GetProductionTrackingData call MUST use the ProvideProductionForecast data model defined in 3.4.
  • IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId.
  • processReferenceType Mode MUST be one of the following items: processStep, capability.
  • partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId.

4.4.2.2 DATA ASSET STRUCTURE

The HTTP GET endpoint introduced in chapter 4.4.1 MUST NOT be called from a partner directly. Rather, it MUST be called via a connector as defined in [CX-0018]. Therefore, the endpoint MUST be offered as an Data Asset.

  • The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique.
  • The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains.
  • The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to identify if there have been updates on an asset definition.
  • The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where the function “unsubscribe” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the connector compliant with [CX-0018] as a reverse proxy by adding parameters to the URL.

An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces {{}} must be substituted with a corresponding value.

Asset definition:

{
"@context": {
"edc": "<https://w3id.org/edc/v0.0.1/ns/>",
"cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)",
"cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)",
"dct": "<https://purl.org/dc/terms/>"
},
"@id": "sis-get-production-tracking-01",
"properties": {
"description": "Get Production Tracking Asset",
"privateProperties": {
},
"cx-common:version": "2.0"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "{SIS\_GET\_PRODUCTION\_FORECAST\_TRACKING}}",
"method": "GET",
"proxyPath": "true",
"contentType": "application/json"
}
}

Access and Usage Policy definition:

{
"@context": {
"@vocab": "<https://w3id.org/edc/v0.0.1/ns/>"
},
"@id": "sis-get-production-tracking-01-policy",
"policy": {
"@context": [
"<https://www.w3.org/ns/odrl.jsonld>",
{
"cx-policy": "<https://w3id.org/catenax/policy/v1.0.0/>"
}
],
"@type": "Policy",
"profile": "cx-policy:profile2405",
"permission": [
{
"action": "use",
"constraint": {
"or": [
{
"leftOperand": "BusinessPartnerNumber",
"operator": "eq",
"rightOperand": "{{POLICY_BPN}}"
}
]
}
}
]
}
}

Contract definition:

{
"@context": {},
"@id": "sis-get-production-tracking-01-contract",
"@type": "ContractDefinition",
"accessPolicyId": "sis-get-production-tracking-01-policy",
"contractPolicyId": "sis-get-production-tracking-01-policy",
"assetsSelector" : {
"@type" : "CriterionDto",
"operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
"operator": "=",
"operandRight": "sis-get-production-tracking-01"
}
}

4.4.2.3 ERROR HANDLING

Every API endpoint defined in Chapter 4.4.1 MUST respond to incoming requests with HTTP status codes as described in [RFC9110]. The status codes for each endpoint are defined in the following sections.

Status CodeDescriptionUsage
200OKThe request has succeeded.
400Bad requestThe server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401UnauthorizedAlthough the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
402Unknown BPNSThe BPNS which is given as parameter is not registered in the data provider database as a direct partner.
403CustomerId unknownThe customerID unknown
405ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource.
421uncomplete Request
422identifierNumber unknownThe identifierID unknown
423billOfMaterialId unknownThe billOfMaterialId unknown
424billOfProcessId unknownThe billOfProcessId unknown
425bomElementId unknownThe bomElementId unknown
426capabilityId unknownThe capabilityId unknown
427processStepId unknownThe processStepId unknown
428other parameters unknownOther parameters unknown

4.5 "ProvideProductionTrackingData" API

The ProvideProductionTrackingDataAPI sends the forecasting data from a Modular Production to the customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a Modular Production MUST be able to send the ProvideProductionForecastData. All participants using the Shop-Floor-Information-Service in the role of a customer or additional third party MUST be able to receive and process the ProvideProductionForecastData.

4.5.1 PRECONDITIONS AND DEPENDENCIES

The ProvideProductionTrackingDataAPI MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC).

4.5.2 API SPECIFICATION

4.5.2.1 API Endpoints & resources

When sending a request to the ProvideProductionForecastData Endpoint, the body MUST be composed out of two information objects: a header and a content. Together they form the HTTP body that MUST be formatted as JSON Request Header.

Note: This is not the HTTP Header but rather part of the HTTP Body.

FieldLevelRequiredPurposeDatatypeExample Value
header
senderBpnCX-Headermandatoryof Meta Model used for compatibilityBpnlCharacteristicBPNL1234567890SE
versionCX-headermandatoryof Meta model used for compatibilityVersionCharacteristic2.0.0
messageIdCX-headermandatoryunique ID for message will be used as requestID for the following communicationUUID00000000-0000-0000-C000-000000000046
contextCX-headermandatoryInformation about the context the message should be considered in, e.g. "MP-Request"stringMUST BEurn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
recipientBpnCX-headermandatoryidentification of the recipientBpnlCharacteristicBPNL0987654321RE
expectedResponseByCX-headermandatoryDeadline for the first responsedate2023-07-02T13:00:00.000+02:00
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
response
versionSIS-Payloadmandatoryof Meta model used for compatibilityVersionCharacteristic1.0.0
catenaXIdSIS-Payloadoptionalidentifier of a product that is registered in a catena-x digital twin registryuuidurn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379
identifierTypeSIS-Payloadmandatoryspecifies the kind of the identifierNumberenumpartInstanceId
identifierNumberSIS-Payloadmandatoryidentifier of a productstringbox-12345678
processStepIdentifierListSIS-PayloadmandatoryLists all process steps for which parameters are providedlist
processStepIdSIS-Payloadoptionalidentifier of a process step referenced in the billOfProcessIdstringFuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01
processParameterValueListSIS-PayloadmandatoryLists all process Parameter provided for a process steplist
processParameterNameSIS-Payloadmandatoryname of a requested process parameterstringDrehmoment_Max
processParameterSemanticIdSIS-Payloadmandatorylink to a semantic that characterizes the type of the process parameterstring0173-1#02-ABK233#001
processParameterValueSIS-Payloadmandatorythe concrete value of a process parameterstring10
processParameterQualitySIS-Payloadmandatoryindicates the quality of the parameters value measurementenumnoValue

The following JSON object gives an example of a valid header and payload.

{
"header" : {
"senderBpn" : "BPNL7588787849VQ",
"relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362",
"expectedResponseBy" : "2023-06-19T21:24:00+07:00",
"context" : "urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0",
"messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"receiverBpn" : "BPNL6666787765VQ",
"sentDateTime" : "2023-06-19T21:24:00+07:00",
"version" : "2.0.0"
},
"response" : {
"identifierNumber" : "box-12345678",
"catenaXId" : "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379",
"identifierType" : "partInstanceId",
"version" : "1.0.0",
"processStepIdentifierList" : [ {
"processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01",
"processParameterValueList" : [ {
"processParameterName" : "Drehmoment_Max",
"semanticId" : "0173-1#02-ABK233#001",
"processParameterQuality" : "ok",
"processParameterValue" : "10"
} ]
} ]
}
}

Available Data Types:

  • The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the endpoints is provided in the corresponding sections of Section 4.4.1.
  • The API ProvideProductionTrackingDatacall MUST use the ProvideProductionTrackingData data model as described in 4.4.1.
  • processParameterQuality MUST be one of the following items: ok, inexact, noValue.

4.5.2.2 DATA ASSET STRUCTURE

The HTTP POST endpoint introduced in chapter 4.5.1 MUST NOT be called from a partner directly. Rather, it MUST be called via a connector compliant with [CX-0018] communication. Therefore, the endpoint MUST be offered as an Data Asset.

  • The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique.
  • The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains.
  • The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to identify if there have been updates on an asset definition.
  • The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where the function “ProvideProductionForecast” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use a connector compliant with [CX-0018] as a reverse proxy by adding parameters to the URL.

An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces {{}} must be substituted with a corresponding value.

Asset definition:

{
"@context": {
"edc": "<https://w3id.org/edc/v0.0.1/ns/>",
"cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)",
"cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)",
"dct": "<https://purl.org/dc/terms/>"
},
"@id": "sis-provide-production-tracking-01",
"properties": {
"description": "Provide Production Tracking Asset",
"privateProperties": {},
"cx-common:version": "2.0"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "{SIS_PROVIDE_PRODUCTION_FORECAST_TRACKING}}",
"method": "POST",
"proxyPath": "true",
"contentType": "application/json"
}
}

Access and Usage Policy definition:

{
"@context": {
"@vocab": "<https://w3id.org/edc/v0.0.1/ns/>"
},
"@id": "sis-provide-production-tracking-01-policy",
"policy": {
"@context": [
"<https://www.w3.org/ns/odrl.jsonld>",
{
"cx-policy": "<https://w3id.org/catenax/policy/v1.0.0/>"
}
],
"@type": "Policy",
"profile": "cx-policy:profile2405",
"permission": [
{
"action": "use",
"constraint": {
"or": [
{
"leftOperand": "BusinessPartnerNumber",
"operator": "eq",
"rightOperand": "{{POLICY_BPN}}"
}
]
}
}
]
}
}

Contract definition:

{
"@context": {},
"@id": "sis-provide-production-tracking-01-contract",
"@type": "ContractDefinition",
"accessPolicyId": "sis-provide-production-tracking-01-policy",
"contractPolicyId": "sis-provide-production-tracking-01-policy",
"assetsSelector" : {
"@type" : "CriterionDto",
"operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
"operator": "=",
"operandRight": "sis-provide-production-tracking-01"
}
}

5 PROCESSES

This section is normative

5.1 "Production Forecast" PROCESS

5.1.1 ACTORS AND ROLES

Any application provider that develops the Production Forecast Aspect of the Shop-Floor-Information-Service has to grant fulfilllment of these requirements.

  • The solution MUST be designed to consider requirements for a trusted usage environment (e.g., identity verification and /or verification process).
  • The solution MUST be designed to require a contractual agreement in compliance with antitrust requirements in the usage environment (e.g., data contracts as a prerequisite for carrying out a data exchange). For reference see CX-0001 guidelines.
  • The solution MUST be designed to limit visibility and/or access to concrete data content as much as possible (e.g., data offer does not yet allow data access).
  • The solution MUST be designed to require the implementation of notice and/or acknowledgement concepts to raise awareness of antitrust issues during use (e.g., helpdesk or pop-up info).
  • The solution MUST be designed to ensure traceability/reconstructability of processes through appropriate documentation and at the same time data sovereignty over concrete data content (e.g., through access, deletion or destination rights).

Any Modular Production, their customer involved logistician and subcontractors (in following called with “all parties”) in the Shop-Floor-Information Production Forecast Service process (i.e., data provider and/or data consumer) MUST fulfill following requirements:

  • All parties are in a contractual relationship with each other and MUST agree to share data related using the Production Forecasts Aspects of the Shop-Floor-Information-Service.
  • All parties MUST manage the access authorization to the Production Forecast Shop-Floor-Information-Service and to its related data.
  • All parties MUST be technically able to participate within the Production Forecast Aspect of Shop-Floor-Information-Service Process.
  • All parties in the role of data provider MUST be able to generate Shop-Floor-Information like forecasting information on the production as well as the current production state. Internal planning data of a Modular Production MUST be made accessible by authorized data consumers (e.g., logisticians or customers) of an upper level in the supply chain.
  • All data providers (factories) MUST ensure that the authorized data consumers will get data directly relevant to them only.
  • All parties in the role of data consumer MUST be able to request and receive data from the factory. Data MUST be exchanged either on request, cyclic and or on notification if a state is changing.
  • It is RECOMMENDED to share forecasting information of a time window of 1 week.

5.2 "Production Tracking" PROCESS

5.2.1 ACTORS AND ROLES

Any application provider that develops the Production Tracking Aspect of the Shop-Floor-Information-Service has to grant fulfillment of these requirements.

  • The solution MUST be designed to consider requirements for a trusted usage environment (e.g., identity verification and /or verification process).
  • The solution MUST be designed to require a contractual agreement in compliance with antitrust requirements in the usage environment (e.g., data contracts as a prerequisite for carrying out a data exchange). For reference see CX-0001 guidelines.
  • The solution MUST be designed to limit visibility and/or access to concrete data content as much as possible (e.g., data offer does not yet allow data access).
  • The solution MUST be designed to require the implementation of notice and/or acknowledgement concepts to raise awareness of antitrust issues during use (e.g., helpdesk or pop-up info).
  • The solution MUST be designed to ensure traceability/reconstructability of processes through appropriate documentation and at the same time data sovereignty over concrete data content (e.g., through access, deletion or destination rights).

Any Modular Production, their customer in the Production Tracking Aspect of the Shop-Floor-Information Service process (i.e., data provider and/or data consumer) MUST fulfilll following requirements:

  • All parties are in a contractual relationship with each other and MUST agree to share data related using the Production Tracking related aspects of the Shop-Floor-Information-Service
  • All parties MUST manage the access authorization to the Production Tracking Shop-Floor-Information-Service and to its related data.
  • All parties MUST be technically able to participate within the Production Tracking Aspect of the Shop-Floor-Information-Service Process.
  • All parties in the role of data provider MUST be able to generate Shop-Floor-Information like tracking information during the production
  • All data providers (factories) MUST ensure that the authorized data consumers will get data directly relevant to them only.
  • All parties in the role of data consumer MUST be able to request and receive data from the factory.

6 REFERENCES

6.1 NORMATIVE REFERENCES

This section is normative

  • CX-0001 EDC Discovery API* Version 1.0.2
  • CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2
  • CX-0010 Business Partner Number Version 2.0.0
  • CX-0018 Dataspace Connectivity Version 3.0.0

6.2 NON-NORMATIVE REFERENCES

This section is non-normative

    n.a.

6.3 REFERENCE IMPLEMENTATIONS

This section is non-normative

  n.a.

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