Skip to content

Chain Protocol SB Datex-II V3

The description of the technical interface for Situation Publications (Situatieberichten or SB) is documented in the chain protocol-SB, described in the underlying paragraphs. This protocol aims to describe how systems for the exchange of DATEX II v3.x connect and exchange data with a payload of the type situationPublication. Exchange 2020 is used for the exchange. The so-called Stateful Push protocol is used. Compared to the European protocol, only delta Synchronization Push is currently not supported.

In the examples below, it is assumed that NDW is the supplier. When NDW is the receiver, the 'ID of the supplier' replaces 'NLNDW' in the 'nationalIdentifier' element.

Data exchange is based on SOAP (version 1.1) over HTTP (version 1.1). For the described method, compression must be used to limit the amount of data traffic. The HTTP header "Accept-Encoding: gzip" should be used for this purpose.

General Requirements

The following requirements apply to both the Push and Pull methods:

  • The consumer must be pre-registered with NDW
  • The consumer must have an NCIS portal account
  • A subscription is required in the NCIS portal for the specific feed to be consumed

Payload

The payload contains the actual DATEX II message with the situation information.

Exchange Information

The exchangeInformation pertains to the exchange between the Supplier and the Client. Using informationManagement, situations can be ended or cancelled. The tables in the paragraphs below contain references such as sd x.x.x. These refer to components in the sequence diagrams as well as to the included XML examples.

Push Method

Systems within the SB chain have an interface available to "push" data to a receiving party. The system of this party must be built to work with the "Exchange 2020 Chain Protocol WSDL".

WSDL descriptions can be found here.

The push method contains several components described below. These include:

  • Administration
  • Start Connection and Deliver Data
  • Maintain Connection
  • Close Connection or Fail
  • Request Snapshot
  • Refusal of Data

Administration

Both the supplying (Supplier) and receiving (Client) parties maintain an offline administration. The supplying system records the following:

  • ClientD
  • End Point where the receiving system wants to receive the data

The receiving system records the following:

  • SupplierID
  • End Point where the supplying system wants to receive the registration

Start Connection and Deliver Data

The client state is 'offline'. The supplying system (Supplier) indicates that it is ready for delivery by sending an openSession message to the receiving system.

sd 1.0 openSession

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of Supplier
exchangeStatus openingSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:openSessionInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                              xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                              xmlns:com="http://datex2.eu/schema/3/common"
                              modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>openingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-04T10:06:11.308965Z</ex:messageGenerationTimestamp>
            </ex:dynamicInformation>
        </stp:openSessionInput>
    </soap:Body>
</soap:Envelope>

The supplying system will do this every 10 minutes until the receiving system responds or until it is manually overridden.

The receiving system responds in one of the following three ways:

  • Success Snapshot on openSession
  • Success Ack on openSession
  • Fail on openSession

Start connection

Success Snapshot on openSession

In this case, when the receiving system receives an Exchange openSession message, it will send back an Exchange snapshotSynchronizationRequest message containing a Session ID. The supplying system will then set the client state to 'online'.

sd 1.1.1 return snapshotSynchronizationRequest

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of Supplier
exchangeStatus openingSession
returnStatus snapshotSynchronisationRequest
sessionID Session ID, determined by client
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:openSessionOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                               xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                               xmlns:com="http://datex2.eu/schema/3/common"
                               modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>openingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>snapshotSynchronisationRequest</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:openSessionOutput>
    </soap:Body>
</soap:Envelope>

The supplying system will then generate a snapshot, which is sent to the receiving party with an ExchangeInformation (payloadDelivery). The data is contained in a payload of the type 'situationPublication'.

sd 1.1.2 payloadDelivery Snapshot

Elements within payload
All relevant situations situation

 

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
updateMethod snapshot
exchangeStatus online
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putSnapshotDataInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                  xmlns:mes="http://datex2.eu/schema/3/messageContainer"
                                  modelBaseVersion="3">
            <mes:payload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xmlns:com="http://datex2.eu/schema/3/common"
                         xmlns:sit="http://datex2.eu/schema/3/situation"
                         xmlns:loc="http://datex2.eu/schema/3/location"
                         xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">
            ....
            </mes:payload>
            <mes:exchangeInformation xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                     modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>snapshot</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                   </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>7892634986</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mes:exchangeInformation>
        </stp:putSnapshotDataInput>
    </soap:Body>
</soap:Envelope>

The receiving system responds with an 'ack' message confirming that the snapshot has been received correctly.

sd 1.1.3 return ack

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus Online
returnStatus Ack
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putSnapshotDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                   xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                   xmlns:com="http://datex2.eu/schema/3/common"
                                   modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>ack</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putSnapshotDataOutput>
    </soap:Body>
</soap:Envelope>

The supplying system then exits the 'Supplier Status offline Open Session' loop and proceeds to the next sequence diagram, 'Maintain Connection' (see the next chapter).

Fail on openSession

When the receiving system sends a fail response to the openSession or if no response is received at all, the supplying system will continue to attempt to establish a connection every ten minutes.

sd 1.2.1 return fail

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus openingSession
returnStatus fail
returnStatusReason optional extra information
codedInvalidityReason e.g.: other
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:openSessionOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                               xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                               xmlns:com="http://datex2.eu/schema/3/common"
                               modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>openingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>fail</ex:returnStatus>
                    <ex:returnStatusReason>
                        <com:values>
                            <com:value>optional extra reason information</com:value>
                        </com:values>
                    </ex:returnStatusReason>
                    <ex:codedInvalidityReason>other</ex:codedInvalidityReason>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:openSessionOutput>
    </soap:Body>
</soap:Envelope>

Maintain Connection

The connection between the supplying system and the receiving system will be maintained by the supplying system. There are two scenarios: 'Data Ready for Payload Push' and 'no data keepAlive'.

Maintain connection

Data ready for payload push

If an update to the data occurs within one minute of the last sent message, it will be sent immediately using an allElementUpdate message, with the data contained in a payload of the type situationPublication.

sd 2.1.1 allElementUpdate

Elements within payload
All updated situations situation
Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
operatingMode onOccurence
updateMethod allElementUpdate
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                          xmlns:mes="http://datex2.eu/schema/3/messageContainer"
                          modelBaseVersion="3">
            <mes:payload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xmlns:com="http://datex2.eu/schema/3/common"
                         xmlns:sit="http://datex2.eu/schema/3/situation"
                         xmlns:loc="http://datex2.eu/schema/3/location"
                         xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">
            ...
            </mes:payload>
            <mes:exchangeInformation xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                     modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:operatingMode>onOccurrence</ex:operatingMode>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                       <ex:sessionID>7892634986</ex:sessionID>
                   </ex:sessionInformation>
                </ex:dynamicInformation>
            </mes:exchangeInformation>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>

sd 2.1.2 return ack

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
returnStatus ack
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                           xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                           xmlns:com="http://datex2.eu/schema/3/common"
                           modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>Exchange2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>ack</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putDataOutput>
    </soap:Body>
</soap:Envelope>

No data keepAlive

If no update to the data is available one minute after sending the last message, the supplying system will send a keep-alive message. The system will continue to send this message every minute until an update to the data is available and an allElementUpdate is sent (as described in the previous paragraph).

sd 2.2.1 keepAlive

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:keepAliveInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                            xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                            xmlns:com="http://datex2.eu/schema/3/common"
                            modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-04T10:06:11.308965Z</ex:messageGenerationTimestamp>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:keepAliveInput>
    </soap:Body>
</soap:Envelope>

sd 2.2.2 return ack

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
returnStatus ack
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:keepAliveOutput  xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                              xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                              xmlns:com="http://datex2.eu/schema/3/common"
                              modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>ack</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:keepAliveOutput>
    </soap:Body>
</soap:Envelope>

CloseSession or Fail

When the receiving system wants to terminate the connection, it must send a closeSessionRequest in response to a push message or a keepAlive message. The supplying system will then respond with a closeSession message. The receiving system will react similarly if a message is rejected by the receiving system (fail).

Additionally, if the receiving system causes a timeout for the supplying system, the supplying system will send a closeSession.

After confirmation or timeout, the supplying system will set the session to 'offline', making the connection inactive and stopping any further data transmission.

Close session

sd 3.1 return closeSessionRequest

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion Exchange 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus closingSession
returnStatus closeSessionRequest
sessionID Session ID, previously obtained with OpenSession
XML Example closeSessionRequest after putDataInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                           xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                           xmlns:com="http://datex2.eu/schema/3/common"
                           modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>closeSessionRequest</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putDataOutput>
    </soap:Body>
</soap:Envelope>
XML Example closeSessionRequest after putSnapshotDataInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putSnapshotDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                   xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                   xmlns:com="http://datex2.eu/schema/3/common"
                                   modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>closeSessionRequest</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putSnapshotDataOutput>
    </soap:Body>
</soap:Envelope>
XML Example closeSessionRequest after keepAliveInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:keepAliveOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                             xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                             xmlns:com="http://datex2.eu/schema/3/common"
                             modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>closeSessionRequest</ex:returnStatus>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:keepAliveOutput>
    </soap:Body>
</soap:Envelope>

sd 3.2 return fail

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
returnStatus fail
returnStatusReason Optional explanation
codedInvalidityReason e.g.: invalidMessage
sessionID Session ID, previously obtained with OpenSession
XML Example after putDataInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                           xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                           xmlns:com="http://datex2.eu/schema/3/common"
                          modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>fail</ex:returnStatus>
                    <ex:returnStatusReason>
                        <com:values>
                            <com:value>XSD validation error at: line 110</com:value>
                        </com:values>
                    </ex:returnStatusReason>
                    <ex:codedInvalidityReason>invalidMessage</ex:codedInvalidityReason>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putDataOutput>
    </soap:Body>
</soap:Envelope>
XML Example after putSnapshotDataInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putSnapshotDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                   xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                   xmlns:com="http://datex2.eu/schema/3/common"
                                   modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>fail</ex:returnStatus>
                    <ex:returnStatusReason>
                        <com:values>
                            <com:value>XSD validation error at: line 110</com:value>
                        </com:values>
                    </ex:returnStatusReason>
                    <ex:codedInvalidityReason>invalidMessage</ex:codedInvalidityReason>
                </ex:returnInformation>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
            </ex:dynamicInformation>
        </stp:putSnapshotDataOutput>
    </soap:Body>
</soap:Envelope>

sd 3.3 closeSession

Elements within exchangeInformation Value
messageType closeSession
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus closingSession
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:closeSessionInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                               xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                               xmlns:com="http://datex2.eu/schema/3/common"
                               modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>closingSession</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-04T10:06:11.308965Z</ex:messageGenerationTimestamp>
                <ex:sessionInformation>
                    <ex:sessionID>7892634986</ex:sessionID>
                </ex:sessionInformation>
           </ex:dynamicInformation>
        </stp:closeSessionInput>
    </soap:Body>
</soap:Envelope>

sd 3.4 return ack

Elements within exchangeInformation Value
messageType return
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus offline
returnStatus ack
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:closeSessionOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                xmlns:com="http://datex2.eu/schema/3/common"
                                modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>offline</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>ack</ex:returnStatus>
                </ex:returnInformation>
            </ex:dynamicInformation>
        </stp:closeSessionOutput>
    </soap:Body>
</soap:Envelope>

Snapshot Request

When a receiving system needs a snapshot to understand the current situation for any reason, it can send a return message with a snapshotSynchronizationRequest in response to any message. The supplying system will generate a snapshot as a result of this request, send it to the receiving system, and then continue with the 'maintain Connection' process. This request can only be made when the session is 'online'. Otherwise, the connection must first be re-established.

Note

If no snapshot is received within two requests, the session will be closed by the receiving system. This will also force a snapshot synchronization.

Request snapshot

sd 4.1 return snapshotSynchronizationRequest

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
exchangeStatus online
returnStatus snapshotSynchronisationRequest
XML Example after keepAliveInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:keepAliveOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                             xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                             xmlns:com="http://datex2.eu/schema/3/common"
                            modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>snapshotSynchronisationRequest</ex:returnStatus>
                </ex:returnInformation>
            </ex:dynamicInformation>
        </stp:keepAliveOutput>
    </soap:Body>
</soap:Envelope>
XML Example after openSessionInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:openSessionOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                               xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                               xmlns:com="http://datex2.eu/schema/3/common"
                               modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>snapshotSynchronisationRequest</ex:returnStatus>
                </ex:returnInformation>
            </ex:dynamicInformation>
        </stp:openSessionOutput>
    </soap:Body>
</soap:Envelope>
XML Example after putDataInput 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataOutput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                           xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                           xmlns:com="http://datex2.eu/schema/3/common"
                           modelBaseVersion="3">
            <ex:exchangeContext>
                <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                <ex:supplierOrCisRequester>
                    <ex:internationalIdentifier>
                        <com:country>NL</com:country>
                        <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                    </ex:internationalIdentifier>
                </ex:supplierOrCisRequester>
            </ex:exchangeContext>
            <ex:dynamicInformation>
                <ex:exchangeStatus>online</ex:exchangeStatus>
                <ex:messageGenerationTimestamp>2021-03-17T19:56:16.266+01:00</ex:messageGenerationTimestamp>
                <ex:returnInformation>
                    <ex:returnStatus>snapshotSynchronisationRequest</ex:returnStatus>
                </ex:returnInformation>
            </ex:dynamicInformation>
        </stp:putDataOutput>
    </soap:Body>
</soap:Envelope>

The supplying system will then generate a snapshot with all relevant situations, which is sent to the receiving party along with an ExchangeInformation (payloadDelivery). The data is contained in a payload of the type 'situationPublication'.

sd 4.2 payloadDelivery Snapshot

Elements within payload
All relevant situations situation

 

Elements within exchangeInformation Value
codedExchangeProtocol statefulPush
exchangeSpecificationVersion 2020
supplierOrCisRequester internationalIdentifier Country, and ID of supplier
updateMethod snapshot
exchangeStatus online
sessionID Session ID, previously obtained with OpenSession
XML Example 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putSnapshotDataInput xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                                  xmlns:mes="http://datex2.eu/schema/3/messageContainer"
                                  modelBaseVersion="3">
            <mes:payload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xmlns:com="http://datex2.eu/schema/3/common"
                         xmlns:sit="http://datex2.eu/schema/3/situation"
                         xmlns:loc="http://datex2.eu/schema/3/location"
                         xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">
            ....
            </mes:payload>
            <mes:exchangeInformation xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                                     modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>snapshot</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NLNDW</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                   </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>7892634986</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mes:exchangeInformation>
        </stp:putSnapshotDataInput>
    </soap:Body>
</soap:Envelope>

The receiving system responds with an 'ack' message confirming that the snapshot has been received correctly.

InformationManagement

Informatie Management

The elementReference element in the informationManagedResourceList section of the InformationManagement section is used to provide the technical information status of a situation, situation component, configuration, or other publication type. From this, it can be determined whether the object referenced is expected to have further updates or not.

Element Type Mandatory Domain
elementReference ElementReference Yes n/a
managementStatus ManagementTypeEnum Yes cancelled, closed, dataChainIssue, outOfRange
reference Reference Yes Describes the reference to the object to which the management status applies.
d2ElementType D2ElementTypeEnum Yes measurementSite, measurementSiteTable, situation, situationRecord, vmsController, vmsControllerTable
managementStatusChangeTime DateTime Yes Describes the time at which the management status was changed.

InformationManagement Situation Publications (Situatieberichten)

Situations and situation components are technically closed or cancelled using the InformationManagement section. This applies to both the situations themselves and to the underlying individual situation components. In addition to this technical closure, when an event is actually ended, the payload with the situation and situation components is also sent again. This payload update includes the final end time of the event in the validity section under overallEndTime. This end time update is always sent before or simultaneously with the provision of the technical end time in InformationManagement, and never later.

Information provision about an event that has not yet actually ended and for which a situation/situation component was previously sent can be suspended. This may apply in cases of a data chain issue (dataChainIssue) or when the event no longer meets publication criteria (outOfRange). If any of these cases occur, it will be indicated using the InformationManagement section, with the reason for the suspension included in the managementStatus element. Unlike a true technical closure, in these cases no payload is sent with an actual end time in the validity section under overallEndTime. Once the actual event is definitively ended, the information provision for the situation/situation component is concluded in the same manner as described in the previous paragraph.

If a suspended event, as described in the previous paragraph, becomes relevant for publication again, the previously used situation/situation component will be reintroduced into the publication with the same ID and a higher version.

Examples of InformationManagement Situation Publications:

XML Example situation ended 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput
              xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:com="http://datex2.eu/schema/3/common"
              xmlns:sit="http://datex2.eu/schema/3/situation"
              xmlns:loc="http://datex2.eu/schema/3/locationReferencing"
              xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
              xmlns:mc="http://datex2.eu/schema/3/messageContainer"
              xmlns:inf="http://datex2.eu/schema/3/informationManagement"
              xmlns:nlx="http://datex2.eu/schema/3/nlxExtensions"
              modelBaseVersion="3">
            <mc:payload
                    xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">

                <com:publicationTime>2023-12-08T09:49:50.713Z</com:publicationTime>
                <com:publicationCreator>
                    <com:country>nl</com:country>
                    <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                </com:publicationCreator>

                <sit:situation id="NDW01_001_SIT">
                    <sit:overallSeverity>unknown</sit:overallSeverity>
                    <sit:situationVersionTime>2023-12-08T09:49:50.713Z</sit:situationVersionTime>
                    <sit:headerInformation>
                        <com:confidentiality>noRestriction</com:confidentiality>
                        <com:informationStatus>real</com:informationStatus>
                    </sit:headerInformation>

                    <sit:situationRecord xsi:type="sit:XXX" id="NDW01_001_SIT_REC" version="4">
                        <sit:situationRecordCreationTime>2023-12-08T09:23:17.546Z</sit:situationRecordCreationTime>
                        <sit:situationRecordVersionTime>2023-12-08T09:49:50.713Z</sit:situationRecordVersionTime>
                        <sit:probabilityOfOccurrence>probable</sit:probabilityOfOccurrence>
                        <sit:source>
                           ...
                        </sit:source>
                        <sit:validity>
                            <com:validityStatus>definedByValidityTimeSpec</com:validityStatus>
                            <com:validityTimeSpecification>
                                <com:overallStartTime>2023-12-08T09:23:17.546Z</com:overallStartTime>
                                <com:overallEndTime>2023-12-08T09:48:50.713Z</com:overallEndTime>
                            </com:validityTimeSpecification>
                        </sit:validity>
                        <sit:generalPublicComment>
                           ...
                        </sit:generalPublicComment>
                        <sit:locationReference xsi:type="loc:PointLocation">
                           ...
                        </sit:locationReference>
                    </sit:situationRecord>
                </sit:situation>
            </mc:payload>
            <mc:exchangeInformation modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2023-12-08T09:48:50.713Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>d674c9b2-e080-499d-8f1e-732b6e0e2fef</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mc:exchangeInformation>
            <mc:informationManagement>
                <inf:informationManagedResourceList>
                    <inf:elementReference>
                        <inf:managementStatus>closed</inf:managementStatus>
                        <inf:reference id="NDW01_001_SIT"/>
                        <inf:_elementReferenceExtension>
                            <inf:elementReferenceExtended>
                                <nlx:d2ElementType>situation</nlx:d2ElementType>
                                <nlx:managementStatusChangeTime>2023-12-08T09:48:50.713Z</nlx:managementStatusChangeTime>
                            </inf:elementReferenceExtended>
                        </inf:_elementReferenceExtension>
                    </inf:elementReference>
                </inf:informationManagedResourceList>
            </mc:informationManagement>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>
XML Example situationRecord ended 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput
              xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:com="http://datex2.eu/schema/3/common"
              xmlns:sit="http://datex2.eu/schema/3/situation"
              xmlns:loc="http://datex2.eu/schema/3/locationReferencing"
              xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
              xmlns:mc="http://datex2.eu/schema/3/messageContainer"
              xmlns:inf="http://datex2.eu/schema/3/informationManagement"
              xmlns:nlx="http://datex2.eu/schema/3/nlxExtensions"
              modelBaseVersion="3">
            <mc:payload
                   xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">

                <com:publicationTime>2023-12-08T09:49:50.713Z</com:publicationTime>
                <com:publicationCreator>
                    <com:country>nl</com:country>
                    <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                </com:publicationCreator>

                <sit:situation id="NDW01_002_SIT">
                    <sit:overallSeverity>unknown</sit:overallSeverity>
                    <sit:situationVersionTime>2023-12-08T09:49:50.713Z</sit:situationVersionTime>
                    <sit:headerInformation>
                        <com:confidentiality>noRestriction</com:confidentiality>
                        <com:informationStatus>real</com:informationStatus>
                    </sit:headerInformation>

                    <sit:situationRecord xsi:type="sit:XXX" id="NDW01_002_SIT_REC" version="4">
                        <sit:situationRecordCreationTime>2023-12-08T09:23:17.546Z</sit:situationRecordCreationTime>
                        <sit:situationRecordVersionTime>2023-12-08T09:49:50.713Z</sit:situationRecordVersionTime>
                        <sit:probabilityOfOccurrence>probable</sit:probabilityOfOccurrence>
                        <sit:source>
                           ...
                        </sit:source>
                        <sit:validity>
                            <com:validityStatus>definedByValidityTimeSpec</com:validityStatus>
                            <com:validityTimeSpecification>
                                <com:overallStartTime>2023-12-08T09:23:17.546Z</com:overallStartTime>
                                <com:overallEndTime>2023-12-08T09:49:50.713Z</com:overallEndTime>
                            </com:validityTimeSpecification>
                        </sit:validity>
                        <sit:generalPublicComment>
                           ...
                        </sit:generalPublicComment>
                        <sit:locationReference xsi:type="loc:PointLocation">
                           ...
                        </sit:locationReference>
                    </sit:situationRecord>
                    <sit:situationRecord xsi:type="sit:XXX" id="NDW01_003_SIT_REC" version="4">
                        <sit:situationRecordCreationTime>2023-12-08T09:23:17.546Z</sit:situationRecordCreationTime>
                        <sit:situationRecordVersionTime>2023-12-08T09:49:50.713Z</sit:situationRecordVersionTime>
                        <sit:probabilityOfOccurrence>probable</sit:probabilityOfOccurrence>
                        <sit:source>
                           ...
                        </sit:source>
                        <sit:validity>
                            <com:validityStatus>definedByValidityTimeSpec</com:validityStatus>
                            <com:validityTimeSpecification>
                                <com:overallStartTime>2023-12-08T09:23:17.546Z</com:overallStartTime>
                            </com:validityTimeSpecification>
                        </sit:validity>
                        <sit:generalPublicComment>
                           ...
                        </sit:generalPublicComment>
                        <sit:locationReference xsi:type="loc:PointLocation">
                           ...
                        </sit:locationReference>
                    </sit:situationRecord>
                </sit:situation>
            </mc:payload>
            <mc:exchangeInformation modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>d674c9b2-e080-499d-8f1e-732b6e0e2fef</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mc:exchangeInformation>
            <mc:informationManagement>
                <inf:informationManagedResourceList>
                    <inf:elementReference>
                        <inf:managementStatus>closed</inf:managementStatus>
                        <inf:reference id="NDW01_002_SIT_REC"/>
                        <inf:_elementReferenceExtension>
                            <inf:elementReferenceExtended>
                                <nlx:d2ElementType>situationRecord</nlx:d2ElementType>
                                <nlx:managementStatusChangeTime>2020-11-04T09:30:47Z</nlx:managementStatusChangeTime>
                            </inf:elementReferenceExtended>
                        </inf:_elementReferenceExtension>
                    </inf:elementReference>
                </inf:informationManagedResourceList>
            </mc:informationManagement>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>
XML Example cancelled 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput
                xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:com="http://datex2.eu/schema/3/common"
                xmlns:sit="http://datex2.eu/schema/3/situation"
                xmlns:loc="http://datex2.eu/schema/3/locationReferencing"
                xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                xmlns:mc="http://datex2.eu/schema/3/messageContainer"
                xmlns:inf="http://datex2.eu/schema/3/informationManagement"
                xmlns:nlx="http://datex2.eu/schema/3/nlxExtensions"
                modelBaseVersion="3">
            <mc:payload
                    xsi:type="sit:SituationPublication" lang="nl" modelBaseVersion="3">

                <com:publicationTime>2024-01-10T14:49:00.000121043Z</com:publicationTime>
                <com:publicationCreator>
                    <com:country>nl</com:country>
                    <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                </com:publicationCreator>

                <sit:situation id="NDW01_001_SIT">
                    <sit:overallSeverity>unknown</sit:overallSeverity>
                    <sit:situationVersionTime>2023-12-08T09:48:50.713Z</sit:situationVersionTime>
                    <sit:headerInformation>
                        <com:confidentiality>noRestriction</com:confidentiality>
                        <com:informationStatus>real</com:informationStatus>
                    </sit:headerInformation>

                    <sit:situationRecord xsi:type="sit:VehicleObstruction"
                                         id="NDW01_001_SIT_REC"
                                         version="4">
                        <sit:situationRecordCreationTime>2023-12-08T09:23:17.546Z</sit:situationRecordCreationTime>
                        <sit:situationRecordVersionTime>2023-12-08T09:49:50.713Z</sit:situationRecordVersionTime>
                        <sit:probabilityOfOccurrence>probable</sit:probabilityOfOccurrence>
                        <sit:source>
                            <com:sourceName>
                                <com:values>
                                    <com:value lang="nl">NDW</com:value>
                                </com:values>
                            </com:sourceName>
                        </sit:source>
                        <sit:validity>
                            <com:validityStatus>definedByValidityTimeSpec</com:validityStatus>
                            <com:validityTimeSpecification>
                                <com:overallStartTime>2024-02-25T19:00:00Z</com:overallStartTime>
                                <com:overallEndTime>2024-02-25T20:00:00Z</com:overallEndTime>
                            </com:validityTimeSpecification>
                        </sit:validity>
                        <sit:generalPublicComment>
                            <sit:comment>
                                <com:values>
                                    <com:value lang="nl">Pijlwagen</com:value>
                                </com:values>
                            </sit:comment>
                        </sit:generalPublicComment>
                        <sit:locationReference xsi:type="loc:PointLocation">
                            <loc:supplementaryPositionalDescription/>
                            <loc:pointByCoordinates>
                                <loc:bearing>250</loc:bearing>
                                <loc:pointCoordinates>
                                    <loc:latitude>51.69019</loc:latitude>
                                    <loc:longitude>5.041351</loc:longitude>
                                </loc:pointCoordinates>
                            </loc:pointByCoordinates>
                        </sit:locationReference>
                        <sit:mobilityOfObstruction>
                            <sit:mobilityType>stationary</sit:mobilityType>
                        </sit:mobilityOfObstruction>
                        <sit:vehicleObstructionType>other</sit:vehicleObstructionType>
                    </sit:situationRecord>
                </sit:situation>
            </mc:payload>
            <mc:exchangeInformation modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>d674c9b2-e080-499d-8f1e-732b6e0e2fef</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mc:exchangeInformation>
            <mc:informationManagement>
                <inf:informationManagedResourceList>
                    <inf:elementReference>
                        <inf:managementStatus>cancelled</inf:managementStatus>
                        <inf:reference id="NDW01_001_SIT_REC"/>
                        <inf:_elementReferenceExtension>
                            <inf:elementReferenceExtended>
                                <nlx:d2ElementType>situationRecord</nlx:d2ElementType>
                                <nlx:managementStatusChangeTime>2020-11-04T09:30:47Z</nlx:managementStatusChangeTime>
                            </inf:elementReferenceExtended>
                        </inf:_elementReferenceExtension>
                    </inf:elementReference>
                </inf:informationManagedResourceList>
            </mc:informationManagement>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>
XML Example datachain issue 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput
                xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:com="http://datex2.eu/schema/3/common"
                xmlns:sit="http://datex2.eu/schema/3/situation"
                xmlns:loc="http://datex2.eu/schema/3/locationReferencing"
                xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                xmlns:mc="http://datex2.eu/schema/3/messageContainer"
                xmlns:inf="http://datex2.eu/schema/3/informationManagement"
                xmlns:nlx="http://datex2.eu/schema/3/nlxExtensions"
                modelBaseVersion="3">

            <mc:exchangeInformation modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>d674c9b2-e080-499d-8f1e-732b6e0e2fef</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mc:exchangeInformation>
            <mc:informationManagement>
                <inf:informationManagedResourceList>
                    <inf:elementReference>
                        <inf:managementStatus _extendedValue="dataChainIssue">_extended</inf:managementStatus>
                        <inf:reference id="NDW01_001_SIT_REC"/>
                        <inf:_elementReferenceExtension>
                            <inf:elementReferenceExtended>
                                <nlx:d2ElementType>situationRecord</nlx:d2ElementType>
                                <nlx:managementStatusChangeTime>2020-11-04T09:30:47Z</nlx:managementStatusChangeTime>
                            </inf:elementReferenceExtended>
                        </inf:_elementReferenceExtension>
                    </inf:elementReference>
                </inf:informationManagedResourceList>
            </mc:informationManagement>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>
XML Example out of range 
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <stp:putDataInput
                xmlns:ex="http://datex2.eu/schema/3/exchangeInformation"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:com="http://datex2.eu/schema/3/common"
                xmlns:sit="http://datex2.eu/schema/3/situation"
                xmlns:loc="http://datex2.eu/schema/3/locationReferencing"
                xmlns:stp="http://datex2.eu/wsdl/statefulPush/2020"
                xmlns:mc="http://datex2.eu/schema/3/messageContainer"
                xmlns:inf="http://datex2.eu/schema/3/informationManagement"
                xmlns:nlx="http://datex2.eu/schema/3/nlxExtensions"
                modelBaseVersion="3">

            <mc:exchangeInformation modelBaseVersion="3">
                <ex:exchangeContext>
                    <ex:codedExchangeProtocol>statefulPush</ex:codedExchangeProtocol>
                    <ex:exchangeSpecificationVersion>2020</ex:exchangeSpecificationVersion>
                    <ex:updateMethod>allElementUpdate</ex:updateMethod>
                    <ex:supplierOrCisRequester>
                        <ex:internationalIdentifier>
                            <com:country>NL</com:country>
                            <com:nationalIdentifier>NDWExample</com:nationalIdentifier>
                        </ex:internationalIdentifier>
                    </ex:supplierOrCisRequester>
                </ex:exchangeContext>
                <ex:dynamicInformation>
                    <ex:exchangeStatus>online</ex:exchangeStatus>
                    <ex:messageGenerationTimestamp>2021-08-11T07:56:57.374114Z</ex:messageGenerationTimestamp>
                    <ex:sessionInformation>
                        <ex:sessionID>d674c9b2-e080-499d-8f1e-732b6e0e2fef</ex:sessionID>
                    </ex:sessionInformation>
                </ex:dynamicInformation>
            </mc:exchangeInformation>
            <mc:informationManagement>
                <inf:informationManagedResourceList>
                    <inf:elementReference>
                        <inf:managementStatus _extendedValue="outOfRange">_extended</inf:managementStatus>
                        <inf:reference id="NDW01_001_SIT_REC"/>
                        <inf:_elementReferenceExtension>
                            <inf:elementReferenceExtended>
                                <nlx:d2ElementType>situationRecord</nlx:d2ElementType>
                                <nlx:managementStatusChangeTime>2020-11-04T09:30:47Z</nlx:managementStatusChangeTime>
                            </inf:elementReferenceExtended>
                        </inf:_elementReferenceExtension>
                    </inf:elementReference>
                </inf:informationManagedResourceList>
            </mc:informationManagement>
        </stp:putDataInput>
    </soap:Body>
</soap:Envelope>

Pull Method

In addition to the previously described Push method, NDW also offers the option to consume data via a Pull method. With this method, the consuming system is responsible for retrieving the data.

Configuration

To use the Pull method:

  1. Log in to the NCIS portal with your account
  2. Navigate to the detail page of your subscription
  3. Here you will find the required configuration data:
  4. URL: The endpoint where the data is available
  5. TOKEN: The authentication token for access to the feed

Implementation

Data consumption is done via an HTTP GET request with Bearer token authentication.

Request Specification

GET {URL}
Authorization: Bearer {TOKEN}
Accept-Encoding: gzip

Parameters:

Parameter Value Required Description
URL As provided in NCIS portal Yes The endpoint for the data feed
Authorization Bearer Yes Bearer token authentication with the provided TOKEN
Accept-Encoding gzip Recommended For data compression

Example Request

curl -X GET "https://backbone.ndw.nu/pull/datex3-srti" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "Accept-Encoding: gzip"

Response

The response contains a DATEX II v3 message with payload of type situationPublication, similar to the Push method.

Response Headers:

Content-Type: application/xml
Content-Encoding: gzip (if supported)

Response Body:

The response body contains the complete DATEX II v3 XML message with all active situations at the time of the request.

Polling Frequency

It is recommended to query the Pull endpoint at an appropriate frequency:

  • Minimum interval: 30 seconds
  • Recommended interval: 60 seconds
  • Maximum interval: Depends on your use case

Too frequent polling can lead to unnecessary system load and possible throttling.

Data Synchronization

When using the Pull method:

  • Each response contains a complete snapshot of all active situations
  • There is no stateful session like with the Push method
  • The consuming system is responsible for detecting changes by comparing with previous responses
  • Pay attention to the situationVersionTime and situationRecordVersionTime fields to detect changes

Error Handling

HTTP Status Codes:

Status Code Meaning Action
200 OK Successful response Process data
401 Unauthorized Invalid or expired token Renew token via NCIS portal
403 Forbidden No access to this feed Check subscription
429 Too Many Requests Rate limit reached Reduce polling frequency
500 Server Error Server problem Retry with exponential backoff
503 Service Unavailable Temporarily unavailable Retry after a few minutes

Security

  • Store the TOKEN securely and never share it with third parties
  • Use HTTPS for all communication
  • Rotate tokens periodically via the NCIS portal
  • Monitor your token usage for unauthorized access

Comparison Push vs Pull

Aspect Push Pull
Initiation Server initiates connection Client initiates requests
Real-time Immediate updates Depends on polling interval
Complexity More complex (stateful sessions) Simpler (stateless)
Network load More efficient (only on changes) Can be inefficient with high polling frequency
Implementation Requires SOAP endpoint at consumer Only HTTP client needed
Reliability Keepalive mechanism Client responsible for polling
Use case Systems requiring real-time updates Periodic synchronization, simple integrations

Monitoring and Support

For both methods:

  • Monitor your subscription status via the NCIS portal
  • Check regularly for updates in the documentation
  • In case of issues, contact NDW support via the NCIS portal
Go back to the previous page