Skip to main content
Release: 24.03 (deprecated)

CX-0068 MP Shop Floor Information Service API 1.0.0

FOR WHOM IS THE STANDARD DESIGNED

ABSTRACT

A Modular Production is part of the value chain. It therefore has to guarantee flexibility and availability on one hand and on the other hand it has to allow product flexibility together with small lot sizes. The effect of disturbances and decision in this network are not limited to a local area, but they have also a big impact to other partners in the value chain network. It is therefore necessary to communicate values from the shop floor directly to other members of the network like the customers or their substitutes like logistians. This communication is realized with the Shop-Floor-Information-Service (SIS). For example a costumer wants to know the estimated date of production, he can therefore use the Shop-Floor-Information-Service to get the information either directly, via cyclic messages or notifications in case of changing calculated production dates. The Shop-Floor-Information-Service uses the GetProductionForecastInformation model and the ProvideProductionForecastInformation model.

1 INTRODUCTION

1.1 AUDIENCE & SCOPE

This section is non-normative

This standard is relevant for

  • Business Application Providers: their role is the implementation of the Shop-Floor-Information-Service
  • Data Providers: mainly modular productions - they have to provide the data necessary 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 delivered products
  • OSIM: the Forecast Data of the SIS can serve as input for a OSIM-simulation

1.2 CONTEXT AND ARCHITECTURE FIT

This section is non-normative

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 are aimed at increasing the flexibility of production 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 networked with the Catena-X network via the connectors standardized in Catena-X. Modular production will offer a Shop-Floor-Information-Service that supplies information about the production status and planning as needed by other use cases. The goal here is to enable individual production (batch 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 in that production can be reconfigured in the event of faults to continue operating 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 fast reactive to changes, it also requires communication of future factory output to the customers.

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. Customer uses the GetProductionForecastInformation call in order to request a production forecast, as specified in CX-0068. The Modular Production generates the required information internally by internal services like a scheduler and answers accordingly by calling ProvideProductionForecastInformation as specified in CX-0068. In case of a cyclic messages or notification mode, the customer has to unsubscribe from the service, if the service is not needed anymore.

SIS Overview

The GetProductionForecastInformation as well as the ProvideProductionForecastInformation is using a AAS serialized as a JSON string which is sent through EDC mechanism: Namely:

  • GetProductionForecastInformation uses "GetProductionForecast" data model and
  • ProvideProductionForecastInformation 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 document (MP) CX - 0069 Shop-Floor-Information-Service Aspect Model v1.0.0. The standard only describes the sending and receiving of Shop-Floor-Information-data through EDC. 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

This section is non-normative

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

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Please refer to: [!LINK Conformity Assessment] for the process of conformity assessment and certification.

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

  • An example GetProductionForecastInformation-JSON as created by their solution
  • An example ProvideProductionForecastInformation-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.

1.4 EXAMPLES

Disturbances of the supply chain always have a major impact of 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 Example for GetProductionForecastInformation

Example JSON string for GetProductionForecastInformation can be found in the data model standard CX-0069 Shop-Floor-Information-Service Aspect Model in chapter 2. GetProductionForecastInformation is the request for getting Shop-Floor-Information. It contains the BPNS of the requesting partner, the customerID, which is the internal customerID in the modular production management and the the orderID, for which forecasting information are 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 an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the modular production EDC and endpoint.

The GetProductionForecastInformation MUST be sent from the requestor of shopfloor information results to the modular production using an HTTP GET request.

An example HTTP request is provided below:

GET /GetProductionForecastInformation HTTP/1.1
Host: {{internal-server}}
Content-Type: application/json
Content-Length: 1123

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

1.4.2 Example for ProvideProductionForecastInformation

Example JSON string for ProvideProductionForecastInformation can be found in the data model standard CX-0069 Shop-Floor-Information-Service Aspect Model in chapter 3. ProvideProductionForecastInformation will return either the current forecasting results in the the case of synchronous mode. In the case of the cyclic or notification mode as well as in case of 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 ProvideProductionForecastInformation mechanism. The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint.

The ProvideProductionForecastInformation data 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 /ProvideProductionForecastInformation HTTP/1.1
Host: {{internal-server}}
Content-Type: application/json
Content-Length: 1079

{
"header": {
"senderBpn": "BPNL1234567890SE",
"relatedMessageId": "00000000-0000-0000-C000-000000000042",
"expectedResponseBy": "2023-07-02T13:00:00.000+02:00",
"context": "urn:samm:io.catenax.MP-SIS-ProvideProductionForecastInformation:1.x.x",
"messageId": "00000000-0000-0000-C000-000000000046",
"recipientBpn": "BPNL0987654321RE",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "urn:samm:io.catenax.shared.message_header:1.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"
}
],
"versionDataModel": "urn:samm:io.catenax.shopfloor_information.production_response:1.0.0",
"communicationMode": "synchronous",
"iterationNumber": 42
}
}

1.4.3 Example for Unsubscribe

Unsubscribe is used to unsubscribe from receiving information in case of a cyclic or notification request. The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. The Unsubscribe request MUST be sent from the consumer of Shop-Floor-Information results 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.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".
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 shopfloor 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 shopfloor 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 "GetProductionForecastInformation" API

This section is normative

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

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

  1. Negotiation between the EDC of the partners using the needed policies
  2. GetProductionForecastInformation(...) - the call of the customer
  3. get the desired information via ProvideProductionForecastInformation(...) - transfered by Modular Production (synchronous, cyclic or notification-like)
  4. Unsubscribe from the "GetProductionForecastInformation" service to receive no further information

SIS Forecast Communication

The two boxes in the middle represent the EDC of the partners. The communication between the respective EDC 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.

2.1 PRECONDITIONS AND DEPENDENCIES

The GetProductionForecastInformation 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 Catena-X standard SOV-001.

2.2 API SPECIFICATION

2.2.1 API Endpoints & resources

When sending a request to the GetProductionForecastInformationEndpoint, 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

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.MP-SIS-GetProductionForecastInformation:1.x.x
sentDateTimeCX-headermandatorytime of requeststring2023-06-19T21:24:00+07:00
versionCX-headermandatoryof Meta model used for compatibilitystringurn:samm:io.catenax.shared.message_header:1.0.0
relatedMessageIdCX-headeroptionalnot used for request; will be used in the following parts to refer to the requestUUID00000000-0000-0000-C000-000000000042
versionDataModelSIS-Payloadmandatoryversion of the datamodelstringurn:samm:io.catenax.shopfloor_information.production_request:1.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.MP-SIS-GetProductionForecastInformation:1.x.x",
"messageId" : "00000000-0000-0000-C000-000000000046",
"recipientBpn" : "BPNL0987654321RE",
"sentDateTime" : "2023-06-19T21:24:00+07:00",
"version" : "urn:samm:io.catenax.shared.message_header:1.0.0"
},
"request" : {
"precisionOfForecast" : {
"timeUnit" : "day",
"value" : 1
},
"offset" : {
"timeUnit" : "day",
"value" : 1
},
"orderId" : "0007",
"customerId" : "BPNL7588787849VQ",
"deviationOfSchedule" : {
"timeUnit" : "day",
"value" : 7
},
"productionForecastForAll" : false,
"versionDataModel" : "urn:samm:io.catenax.shopfloor_information.production_request:1.0.0",
"notificationInterval" : {
"timeUnit" : "day",
"value" : 2
},
"communicationMode" : "synchronous"
}
}

2.2.2 Available Data Types

The API GetProductionForecastInformation call MUST use the GetProductionForecast data model (CX-0069)

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 2.2.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

2.2.3 EDC Data Asset Structure

The HTTP GET endpoint introduced in chapter 2.2.1 MUST NOT be called from a partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC 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 “GetProductionForecastInformation” is implemented.
  • Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL.

An example EDC 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
{
"asset": {
"properties": {
"asset:prop:id": "sis-request-01",
"asset:prop:description": "sisRequest Endpoint",
"asset:prop:version": "1.0.0"

}
},
"dataAddress": {
"properties": {
"type": "HttpData",
"baseUrl": "{{sis_REQUEST_ENDPOINT}}",
"proxyPath": true
}
}
}
// Access and Usage Policy definition

"uid": "sis-request-01-policy",
"policy": {
"prohibitions": [],
"obligations": [],
"permissions": [
{
"target": "sis-request-01",
"edctype": "dataspaceconnector:permission",
"action": {
"type": "USE"
},
"constraints": []
}
]
}
}
// Contract definition
{
"id": "sis-request-01-contract",
"criteria": [
{
"operandLeft": "asset:prop:id",
"operator": "=",
"operandRight": "sis-request-01"
}
],
"accessPolicyId": "sis-request-01-policy",
"contractPolicyId": "sis-request-01-policy"
}

2.2.4 Error Handling

Every API endpoint defined in Chapter 2.2.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.
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

3 "ProvideProductionForecastInformation" API

This section is normative

The ProvideProductionForecastInformation API sends the forecasting data from a modular production to the customer or a third party on the next lower level. All participants participating using the Shop-Floor-Information-Service in the role of a a modular production MUST be able to send the ProvideProductionForecastInformation. 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 ProvideProductionForecastInformation.

3.1 PRECONDITIONS AND DEPENDENCIES

The ProvideProductionForecastInformation 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 Catena-X standard SOV-001.

3.2 API SPECIFICATION

3.2.1 API Endpoints & resources

When sending a request to the ProvideProductionForecastInformation 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
versionCX-headermandatoryof Meta model used for compatibilitystringurn:samm:io.catenax.shared.message_header:1.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.MP-SIS-ProvideProductionForecastInformation:1.x.x
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
versionDataModelSIS-Payloadmandatoryversion of the datamodelstringurn:samm:io.catenax.shopfloor_information.production_response:1.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 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.MP-SIS-ProvideProductionForecastInformation:1.x.x",
"messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9",
"recipientBpn": "BPNL6666787765VQ",
"sentDateTime": "2023-06-19T21:24:00+07:00",
"version": "urn:samm:io.catenax.shared.message_header:1.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"
}
],
"versionDataModel": "urn:samm:io.catenax.shopfloor_information.production_response:1.0.0",
"communicationMode": "synchronous",
"iterationNumber": 6
}
}

3.2.2 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.1

The API ProvideProductionForecastInformation call MUST use the ProvideProductionForecast data model (CX-0069)

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

3.2.3 EDC Data Asset Structure

The HTTP POST endpoint introduced in chapter 3.2.1 MUST NOT be called from a partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC 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 the EDC as a reverse proxy by adding parameters to the URL.

An example EDC 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
{
"asset": {
"properties": {
"asset:prop:id": "sis-provide-01",
"asset:prop:description": "sisProvide Endpoint",
"asset:prop:version": "1.0.0"

}
},
"dataAddress": {
"properties": {
"type": "HttpData",
"baseUrl": "{{sis_Provide_ENDPOINT}}",
"proxyPath": true
}
}
}

// Access and Usage Policy definition

"uid": "sis-provide-01-policy",
"policy": {
"prohibitions": [],
"obligations": [],
"permissions": [
{
"target": "sis-provide-01",
"edctype": "dataspaceconnector:permission",
"action": {
"type": "USE"
},
"constraints": []
}
]
}
}

// Contract definition
{
"id": "sis-provide-01-contract",
"criteria": [
{
"operandLeft": "asset:prop:id",
"operator": "=",
"operandRight": "sis-provide-01"
}
],
"accessPolicyId": "sis-provide-01-policy",
"contractPolicyId": "sis-provide-01-policy"
}

3.2.4 Error Handling

Every API endpoint defined in Chapter 2.2.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.
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.
420lowerAccuracyOfPrecisionthe returned data has a lower precision than requested
421noForecastAvailableNo data available

4 "Unsubscribe" API

This section is normative

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.1 PRECONDITIONS AND DEPENDENCIES

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 Catena-X standard SOV-001.

4.2 API SPECIFICATION

4.2.1 API Endpoints & resources

The unsubscribe API is implemented as an HTTP DELETE request with the relatedMessageID as a parameter, which is sent without any HTTP body.

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

The parameter related messageID is defined as follows:

FieldLevelREQUIREDPurposeDatatypeExample Value
relatedMessageIdCX-HeadermandatoryUUID of request messageId for identification of related messagesUUID00000000-0000-0000-C000-000000000042

4.2.2 Available Data Types

The unsubscribe does not require any payload.

4.2.3 EDC Data Asset Structure

The HTTP DELETE endpoint introduced in chapter 4.2.1 MUST NOT be called from a partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC 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 EDC as a reverse proxy by adding parameters to the URL.

An example EDC 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
{
"asset": {
"properties": {
"asset:prop:id": "sis-unsubscribe-01",
"asset:prop:description": "sis-unsubscribeEndpoint",
"asset:prop:version": "1.0.0"

}
},
"dataAddress": {
"properties": {
"type": "HttpData",
"baseUrl": "{{sis_unsubscribe_ENDPOINT}}",
"proxyPath": true
}
}
}



// Access and Usage Policy definition

"uid": "sis-unsubscribe-01-policy",
"policy": {
"prohibitions": [],
"obligations": [],
"permissions": [
{
"target": "sis-unsubscribe-01",
"edctype": "dataspaceconnector:permission",
"action": {
"type": "USE"
},
"constraints": []
}
]
}
}



// Contract definition
{
"id": "sis-unsubscribe-01-contract",
"criteria": [
{
"operandLeft": "asset:prop:id",
"operator": "=",
"operandRight": "sis-unsubscribe-01"
}
],
"accessPolicyId": "sis-unsubscribe-01-policy",
"contractPolicyId": "sis-unsubscribe-01-policy"
}

4.2.4 Error Handling

Every API endpoint defined in Chapter 2.2.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

5 REFERENCES

5.1 NORMATIVE REFERENCES

5.2 NON-NORMATIVE REFERENCES

This section is non-normative

5.3 REFERENCE IMPLEMENTATIONS

This section is non-normative

ANNEXES

FIGURES

This section is non-normative

TABLES

This section is non-normative

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