Chain protocol TMIS

Chain protocol TMIS

Technical description system interfaces

For all interfaces, both a Push (The delivery system initiates the transmission of data) and a Pull (the receiving system initiates the transmission) mechanism is available. Exchange of data takes place on the basis of SOAP (version 1.1) over HTTP (version 1.1). The way in which authentication is applied depends on the chosen mechanism. The authentication can consist of a combination of username and password and/or one or more IP addresses which are allowed. For all described methods, compression must be used to limit the amount of data traffic. For all described methods, use must be made of compression to limit the amount of data traffic. For this the HTTP headers “Accept-Encoding: gzip” and En “Content-Encoding: gzip” should be used.

MRM/MSI data

The description of the technical interface for MRM/MSI data is recorded in the chain protocol MRM/MSI. The interface is described in the following subsections. This protocol is intended to provide a description of how user can obtain MRM/MSI data from NCIS (NDW central information system). Within the chain protocol MRM/MSI two methods for obataining the data are described (Push method and Pull method). The Push method provides the user of the data once with a snapshot (the complete current situation), and will then only send updates. With the Pull method, users of the data can always retrieve a snapshot with an agreed interval.

Push methode

NCIS has an interface available to “push” data to a receiving party. The system of this party must be built to work with both the “registration WSDL” and the “data reception WSDL “.

TODO:

The push method contains a number of components that are described below.

  • Administration;
  • Ready for delivery;
  • Sign up for delivery;
  • Start delivery;
  • Maintaining connection;
  • Restart delivery;
  • Unsubscribe from delivery;
  • Refuse the receiving system;
  • Reject data.

Administration

Both the supplying (NCIS) and the receiving (Client) party keep an offline administration. This is registered with the supplying system:

  • Endpoint on which the decreasing system wants to receive the data;
  • Username and Password with which the decreasing system will register.

With the receiving system the following is registered:

  • End Point on which the delivery system wants to receive the registration.

Ready for delivery

The supplying system indicates that it is ready for delivery by sending a Keep-Alive message to the decreasing system. The exchange element of this Keep-Alive message contains the following values:

Elements within exchange value
keepAlive true
requestType subscription
deliveryBreak true

To make a distinguish between a regular keepAlive and a keepAlive for ready delivery, the deliveryBreak element is included in this keepAlive. No data is exchanged at this time.

Example keep-alive (with deliverybreak) message:

MRM
MSI

If the receiving system receives such a Keep-Alive message, it will send it an Acknowledge message, and then sign up for delivery at the registration web service.

Example acknowledge message:

MRM
MSI

../../../_images/klaar_voor_levering.png

Sign up for delivery

The receiving system logs on to the supplying system with the registerRequest in accordance with the WSDL of the registration web service. If there is no correct register response from the supplying system, the register request is sent again. This is repeated every 10 minutes until a registerResponse is received. After the supplying system has sent the registerResponse, it starts the delivery of data via the data reception web service. The receiving system must start with this, even if the supplying system has not yet made it known that it is ready for delivery. The next steps in the procedure are the same as described above.

If after 3 attempts there is no response from the supplying system, an incident will have to be reported to the service desk of the supplying party. This only applies if the supplying system has made it known that it is ready for delivery by sending keepAlives.

The values ​​to be used within the registerRequest are:

registerRequest value
clientIdentification Agreed username receiving system
clientPassKey Agreed password receiving system

Example registerRequest message:

MRM
MSI

The values ​​to be used within registerResponse:

registerResponse value
clientIdentification Appointed username receiving system

Example registerResponse message:

MRM
MSI

../../../_images/aanmelden_voor_levering.png

Start delivery

After the registration of the receiving system at the delivery system has been successful, delivery can commence. The supplying system is the first to send a message with the current state of affairs (Snapshot). In this message, the updateMethod element is filled with the value snapshot. This message is answered by the receiving system with an acknowledge message.

The snapshot message from the supplying system must contain the following values:

Elements within exchange value
subscriptionState active
updateMethod snapshot
MRM
MSI

The Acknowledging message from the receiving system must contain the following values:

Elements within exchange value
response acknowledge

Example acknowledge message:

MRM
MSI

Immediately thereafter, a message is sent by the supplying system (updateMethod change message) indicating that from now on there will only be updates to the snapshot sent. In this message the updateMethod element is filled with the value allElementUpdate, this message contains only the element exchange. The payload will therefore not be present.

The receiving system responds to this message with an acknowledge message.

The allElementUpdate message from the Supplier must contain the following values:

Elements within Subscription value
subscriptionState active
updateMethod allElementUpdate

Example updateMethod change message:

MRM
MSI

The acknowledgment of the decreasing system must contain the following values:

Elements within exchange value
response acknowledge

Example acknowledge message:

MRM
MSI

After this, the connection is maintained.

../../../_images/begin_levering.png

Maintaining connection

The connection between the supplying system and the receiving system will be maintained by the supplying system. As long as there is no update on the data, the delivery system will send a keep-alive message every 5 minutes, if there is an update on the data, it will be sent by means of an allElementUpdate message where the data is in the payload element. The keep-alive or the AllElementUpdate is answered with an acknowledgment by the decreasing system. If this acknowledgment is not received, the supplying system will resubmit the message. The supplying system tries to send a message up to three times.

If it is still not possible to deliver the message below, a deliveryBreak message will be sent and the delivery system will go to ready-for-delivery mode. If the receiving system has not received messages from the delivery system for more than 11 minutes, it will go to the unsubscribe from delivery mode.

The exchange element of the Keep-Alive message contains the following values:

Elements within exchange value
keepAlive true

Example keep-alive:

MRM
MSI

The allElementUpdate message from the supplying system must contain the following values:

Elements within Subscription value
subscriptionState active
updateMethod allElementUpdate

Example allElementUpdate message:

MRM
MSI

The acknowledge message from the decreasing system must contain the following values:

Elements within exchange value
response acknowledge

Example acknowledge message:

MRM
MSI

The deliveryBreak message from the supplying system contains the following values:

Elements within exchange value
deliveryBreak true

Example deliverybreak message:

MRM
MSI

../../../_images/onderhouden_verbinding.png

Restart delivery

The receiving system can send the delivering system a request for a new snapshot. For this purpose, the requestSituationUpdatesRestartRequest message from the registration web service. After the delivery system has received the message, it will go to the start delivery procedure.

The values ​​to be used within the requestSituationUpdatesRestartRequest message are:

Element value
clientIdentification Agreed username receiving system
clientPassKey Agreed password receiving system

Example requestSituationUpdatesRestartRequest message:

MRM
MSI

Unsubscribe from delivery;

The receiving system can cancel the delivery at the supplying system. An unRegisterRequest can be sent for this. After the delivery system has received the unRegisterRequest it will answer, on the data reception web service, with an AllElementUpdate containing SubscriptionState on suspended (suspend message). The receiving system will have to register again in order to receive this data from the supplying system.

If the cancellation is done after the data is rejected, the receiving system will wait with registration until the supplying system has made it known that it is ready for delivery.

The values ​​to be used within the unregisterRequest message are:

Element value
clientIdentification Agreed username receiving system
clientPassKey Agreed password receiving system

Example unRegisterRequest message:

MRM
MSI

The values ​​to be used within the suspend message are:

Elements within exchange value
subscriptionState suspended
updateMethod allElementUpdate

Example suspend message:

MRM
MSI

../../../_images/afmeld_procedure.png

If UnregisterRequest, which is sent after 11 minutes no data has been received and no delivery break has been received, is not answered by the supplying system, an incident must be reported to the service desk of the supplying party. The supplying system can also unsubscribe itself for delivery at the receiving system. For this purpose, an AllElementUpdate with SubscriptionState must be sent on suspended from the delivery system.

Refuse the receiving system

If the receiving system registers with the wrong username or password, the supplying system will send a message back to the data reception web service.

This wrongPartner message contains an Exchange element whose elements have the following values:

Elements within exchange value
denyReason wrongPartner
Response requestDenied

Example wrongPartner message:

MRM
MSI

../../../_images/weigering_client.png

Reject data

There are two times when the receiving system can refuse the data sent by the supplying system: 1. When receiving a snapshot. • The receiving system will cancel the delivery. 2. When receiving an allElementUpdate. • The delivery system will go to the start delivery mode. When refusing data, a requestDenied message is sent and the denyReason element must always be filled.

Example requestDenied message:

MRM
MSI

Pull procedure

A supplying system is also equipped with functionality to publish data at the request of a receiving system. The pull method is implemented on the basis of the “simple http server profile”, which means that the receiving system makes an HTTP request and receives the data in the body of the response. This data is presented in the same format as the push method. To maintain interoperability between these two methods, the data in the pull method is also packaged in a SOAP envelope.