Ketenprotocol TMIS

Ketenprotocol TMIS

Technische beschrijving systeem interfaces

Voor alle interfaces geldt dat er zowel een Push- (Het aanleverende systeem initieert de verzending van gegevens) als een Pull (het afnemende systeem initieert de verzending) mechanisme beschikbaar is. Uitwisseling van gegevens geschiedt op basis van SOAP (versie 1.1) over HTTP (versie 1.1). De wijze waarop authenticatie wordt toegepast is afhankelijk van het gekozen mechanisme. De authenticatie kan bestaan uit een combinatie van gebruikersnaam en wachtwoord en/of één of meerdere toegestane ip adressen. Voor alle beschreven methodes geldt dat er gebruik gemaakt moet worden van compressie om de hoeveelheid data verkeer te beperken. Hiervoor dienen de HTTP headers “Accept-Encoding: gzip” en En “Content-Encoding: gzip” gebruikt te worden.

MRM/MSI gegevens

De beschrijving van de technische interface voor MRM/MSI gegevens is vastgelegd in het, in de onderliggende paragrafen beschreven, ketenprotocol-MRM/MSI. Dit protocol is bedoeld om een beschrijving te geven hoe afnemers MRM/MSI data van NCIS (NDW centraal informatie systeem) kunnen afnemen. Binnen het ketenprotocol-MRM/MSI worden er twee methodes voor data afname beschreven. Te weten de Push methode en de Pull methode. De Push methode voorziet de afnemer eenmalig van een snapshot (de volledige actuele situatie), en zal daarna enkel updates versturen. Met de Pull methode kunnen afnemers met een afgesproken interval steeds een snapshot ophalen.

Push methode

NCIS heeft een interface beschikbaar om data te “pushen” naar een afnemende partij. Het systeem van deze partij moet gebouwd zijn om te werken met zowel de “registratie WSDL” als de ”“data ontvangst WSDL” .

TODO:

De push methode bevat een aantal onderdelen die hieronder beschreven worden. Het gaat om:

  • Administratie;
  • Klaar voor levering;
  • Aanmelden voor levering;
  • Begin levering;
  • Onderhouden verbinding;
  • Herstart levering;
  • Afmelden voor levering;
  • Weigeren van afnemend systeem;
  • Weigeren van data.

Administratie

Zowel de aanleverende (NCIS) als de afnemende (Client) partij houden een offline administratie bij. Hierin staat geregistreerd bij het aanleverend systeem:

  • Endpoint waarop het afnemende systeem de data wil ontvangen;
  • Gebruikersnaam en Wachtwoord waarmee het afnemende systeem zal registeren.

Hierin staat geregistreerd bij het afnemende systeem:

  • End Point waarop de het aanleverend systeem de registratie wil ontvangen.

Klaar voor levering

Het aanleverend systeem maakt kenbaar dat het klaar is voor levering door een Keep-Alive bericht te sturen naar het afnemend systeem. Het exchange element van dit Keep-Alive bericht bevat de volgende waarden:

Elementen binnen exchange waarde
keepAlive true
requestType subscription
deliveryBreak true

Om onderscheid te maken tussen een gewone keepAlive en een keepAlive voor klaar voor levering is in deze keepAlive het element deliveryBreak opgenomen. Er wordt namelijk nog geen data uitgewisseld op dit moment.

Voorbeeld keep-alive (met deliverybreak) bericht:

MRM
MSI

Als het afnemend systeem zo’n Keep-Alive bericht ontvangt zal het het een Acknowledge bericht sturen, en zich dan aanmelden voor levering op de registratie webservice.

Voorbeeld acknowledge bericht:

MRM
MSI

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

Aanmelden voor levering

Het afnemend systeem meldt zich bij het aanleverend systeem aan met het registerRequest conform de WSDL van de registratie webservice. Komt er van het aanleverend systeem geen correcte registerResponse dan wordt het register verzoek opnieuw gestuurd. Dit wordt iedere 10 minuten herhaald totdat er een registerResponse wordt ontvangen. Nadat het aanleverend systeem het registerResponse heeft gestuurd wordt er begonnen met de levering van data via de data ontvangst webservice. Het afnemend systeem moet hiermee beginnen ook als het aanleverend systeem nog niet kenbaar heeft gemaakt dat het klaar is voor levering. De procedure is verder het zelfde als hierboven beschreven. Indien er na 3 pogingen geen reactie komt van het aanleverend systeem zal er een incident aangemeld moeten worden bij de servicedesk van de leverende partij. Dit geldt alleen als het aanleverend systeem kenbaar gemaakt heeft klaar te zijn voor levering doormiddel van het versturen van keepAlives.

De te gebruiken waardes binnen het registerRequest zijn:

registerRequest waarde
clientIdentification Afgesproken gebruikersnaam afnemend systeem
clientPassKey Afgesproken wachtwoord afnemend systeem

Voorbeeld registerRequest bericht:

MRM
MSI

De te gebruiken waardes binnen het registerResponse zijn:

registerResponse waarde
clientIdentification Afgesproken gebruikersnaam afnemend systeem

Voorbeeld registerResponse bericht:

MRM
MSI

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

Begin levering

Nadat de aanmelding van het afnemend systeem bij het aanleverend systeem succesvol is verlopen kan er begonnen worden met de levering. Het aanleverend systeem stuurt als eerste een bericht met de actuele stand van zaken (Snapshot). In dit bericht is het element updateMethod gevuld met de waarde snapshot. Dit bericht wordt door het afnemend systeem beantwoord met een acknowledge bericht.

Het snapshot bericht van het aanleverend systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
subscriptionState active
updateMethod snapshot
MRM
MSI

Het Acknowlegde bericht van het afnemend systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
response acknowledge

Voorbeeld acknowledge bericht:

MRM
MSI

Direct daarna wordt er door het aanleverend systeem een bericht gestuurd (updateMethod change bericht) waarmee wordt aangegeven dat er vanaf nu alleen updates ten opzichte van het verstuurde snapshot. Het element updateMethod is in dit bericht gevuld met de waarde allElementUpdate, dit bericht bevat alleen het element exchange. De payload zal dus niet aanwezig zijn. Het afnemend systeem beantwoordt dit bericht met een acknowledge bericht.

Het allElementUpdate bericht van de Supplier moet de volgende waardes bevatten:

Elementen binnen Subscription waarde
subscriptionState active
updateMethod allElementUpdate

Voorbeeld updateMethod change bericht:

MRM
MSI

Het acknowledgement van het afnemend systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
response acknowledge

Voorbeeld acknowledge bericht:

MRM
MSI

Hierna wordt overgaan tot het onderhouden van de verbinding.

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

Onderhouden verbinding

De verbinding tussen het aanleverend systeem en het afnemend systeem zal worden onderhouden door het aanleverend systeem. Zolang er geen update op de data te versturen is zal het aanleverend systeem iedere 5 minuten een keep-alive bericht sturen, als er wel een update op de data is zal deze verstuurd worden doormiddel van een allElementUpdate bericht waarbij de data zich bevindt in het payload element. De keep-alive of de AllElementUpdate wordt beantwoord met een acknowledgement door het afnemend systeem. Als deze acknowledgement niet wordt ontvangen zal het aanleverend systeem het bericht opnieuw aanbieden. Het aanleverend systeem probeert een bericht maximaal drie maal te versturen naar een afnemend systeem. Mocht het hierna nog steeds niet gelukt zijn om het bericht af te leveren wordt er een deliveryBreak bericht gestuurd en gaat het aanleverend systeem naar de modus klaar voor levering. Als het afnemend systeem langer dan 11 minuten geen berichten van het aanleverend systeem heeft ontvangen zal deze naar de afmeld methode gaan.

Het exchange element van het Keep-Alive bericht bevat de volgende waarden:

Elementen binnen exchange waarde
keepAlive true

Voorbeeld keep-alive:

MRM
MSI

Het allElementUpdate bericht van het aanleverend systeem moet de volgende waardes bevatten:

Elementen binnen Subscription waarde
subscriptionState active
updateMethod allElementUpdate

Voorbeeld allElementUpdate bericht:

MRM
MSI

Het acknowledge bericht van het afnemend systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
response acknowledge

Voorbeeld acknowledge bericht:

MRM
MSI

Het deliveryBreak bericht van het aanleverend systeem bevat de volgende waardes:

Elementen binnen exchange waarde
deliveryBreak true

Voorbeeld deliverybreak bericht:

MRM
MSI

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

Herstart levering

Het afnemend systeem kan het aanleverend systeem een verzoek sturen om een nieuw snapshot. Hiervoor is het bericht requestSituationUpdatesRestartRequest van de registratie webservice. Nadat het aanleverend systeem het bericht ontvangen heeft zal deze naar de begin levering procedure gaan. De te gebruiken waardes binnen het requestSituationUpdatesRestartRequest bericht zijn: Element Waarde clientIdentification Afgesproken gebruikersnaam afnemend systeem clientPassKey Afgesproken wachtwoord afnemend systeem

Element waarde
clientIdentification Afgesproken gebruikersnaam afnemend systeem
clientPassKey Afgesproken wachtwoord afnemend systeem

Voorbeeld requestSituationUpdatesRestartRequest bericht:

MRM
MSI

Afmelden voor levering

Het afnemend systeem kan zich bij het aanleverend systeem afmelden voor de levering. Hiervoor kan een unRegisterRequest worden verstuurd. Nadat het aanleverend systeem deze heeft ontvangen zal deze antwoorden, op de data ontvangst webservice, met een AllElementUpdate met daarin SubscriptionState op suspended (suspend bericht). Het afnemend systeem zal zich opnieuw moeten aanmelden wil deze data ontvangen van het aanleverend systeem. Indien de afmelding gedaan wordt na het weigeren van data zal het afnemend systeem wachten met aanmelden totdat het aanleverend systeem kenbaar gemaakt heeft klaar te zijn voor levering. De te gebruiken waardes binnen het unregisterRequest bericht zijn:

Element waarde
clientIdentification Afgesproken gebruikersnaam afnemend systeem
clientPassKey Afgesproken wachtwoord afnemend systeem

Voorbeeld unRegisterRequest bericht:

MRM
MSI

De te gebruiken waardes binnen het suspend bericht zijn:

Elementen binnen exchange waarde
subscriptionState suspended
updateMethod allElementUpdate

Voorbeeld suspend bericht:

MRM
MSI

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

Indien UnregisterRequest, die verstuurd wordt nadat er 11 minuten geen data is ontvangen en ook geen deliverybreak is ontvangen, niet beantwoord wordt door het aanleverend systeem moet er een incident ingemeld worden bij de servicedesk van de aanleverende partij. Het aanleverende systeem kan zich ook zelf afmelden voor levering bij het afnemende systeem. Hiervoor dient er vanuit het aanleverende systeem een AllElementUpdate met daarin SubscriptionState op suspended gestuurd te worden.

Weigeren van afnemend systeem

Indien het afnemend systeem zich aanmeld met verkeerde gebruikersnaam of wachtwoord zal het aanleverend systeem een bericht terug sturen naar de data ontvangst webservice. Dit wrongPartner bericht bevat een Exchange element waarvan de elementen de volgende waarden hebben:

Elementen binnen exchange waarde
denyReason wrongPartner
Response requestDenied

Voorbeeld wrongPartner bericht:

MRM
MSI

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

Weigeren van data

Er zijn twee momenten waarop het afnemend systeem de data die verstuurd is door het aanleverend systeem kan weigeren: 1. Bij het ontvangen van een snapshot. • Hierbij zal het afnemend systeem zich afmelden voor de levering. 2. Bij het ontvangen van een allElementUpdate. • Hierbij zal het aanleverend systeem naar de modus begin levering gaan. Bij het weigeren van data wordt er een requestDenied bericht gestuurd en moet het element denyReason altijd gevuld zijn.

Voorbeeld requestDenied bericht:

MRM
MSI

Pull procedure

Een aanleverend systeem is tevens uitgerust met functionaliteit om gegevens, op verzoek van het afnemend systeem te publiceren. De pull methode is geïmplementeerd op basis van het “simple http server-profile”, wat betekent dat de afnemer een HTTP-request doet en in de body van de response de gegevens krijgt. Deze gegevens worden in hetzelfde formaat aangeboden als bij de push methode. Om interoperabiliteit te behouden tussen deze twee methoden wordt de data bij de pull methode ook in een SOAP envelope verpakt.