Toelichting en voorbeelden wsdl stuurGBAbericht

MEMO Toelichting en voorbeelden wsdl stuurGBAbericht

1. Algemene beschrijving van de stuurGBABericht webserivce

De webservice verleent drie diensten: Controleren PL, Uitwisselen van LO berichten (sPoed) en test webservice (Echo),
Omdat verschillende diensten via een webservice (met 1 wsdl) worden geleverd, vertonen deze diensten op punten gelijk gedrag. Hieronder worden de belangrijkste overeenkomsten en verschillen beschreven.

Figuur 1. Algemene beschrijving

Image

Functionele overeenkomsten zijn:

• Alle diensten in stuurGBABericht draaien om de uitwisseling van 'GBA-berichten'.
• Elke dienst voert een actie uit op een ontvangen bericht (verwerken, controleren etctera);
• Elke dienst bestaat uit een of meer acties;
• Elke actie heeft een vraag- en een antwoordbericht (request resp. response);
• De gewenste actie wordt aangegeven in het vraagbericht in de body van het bericht.
• Het resultaat van de gewenste actie wordt teruggegeven in een antwoordbericht in de body van het bericht

Overeenkomsten in de implementatie zijn:

• StuurGBABericht maakt gebruik van TLS en HTTP basic authentication;
• StuurGBABericht is een SOAP 1.1 webservice over HTTP;
• De SOAP body van een vraagbericht bevat een <stuurGBABerichtRequest als 'root';
• Een vraagbericht bevat altijd het element actie met daarin de naam van de actie;
• Een vraagbericht bevat afhankelijk van de gevraagde actie de elementen gbabericht aanleiding en berichtnummer
• Een antwoordbericht bevat in de body stuurGBABerichtResponse als root;
• Een antwoordbericht bevat altijd het verplichte element resultaatcode. De invulling daarvan verschilt per actie;
• Een antwoordbericht bevat altijd het element referentie; met daarin de activiteit ID van de webservice actie;
• Een activiteit ID is een getal van maximaal 12 posities.
• Voor alle berichten geldt UTF-8 encodering;
• Regelovergangen volgen de XML standaard (LF), zie http://www.w3.org/TR/REC- xml/#sec-line-ends;
• Het GBA-bericht dat meegestuurd wordt, is geencodeerd in Teletex maar wel ingebed in Unicode. Zie ook de uitleg bij Voorbeeld Appendix A;
• Gebruik van character entities in de berichtinhoud en uitsluiting van het gebruik van Form Feed;
• Alle parameters (elementen en element-inhoud) zijn case sensitive;
• De wsdl en xsd zijn opgenomen in Appendix B.

Gebruik van het SOAPAction HTTP request header veld

De WSDL voor stuurGBABericht specificeert geen SOAPAction HTTP header waarde. De SOAPAction header zelf is volgens de SOAP-specificatie echter wel verplicht. In een vraagbericht moet een SOAPAction zonder waarde mee worden geven. Wanneer een gevulde SOAPAction wordt aangeboden in de HTTP volgt een fout(bericht).

Verschillen tussen de diensten zijn:

• Elk van de diensten vereist een andere autorisatie.
• sPoed maakt gebruik van WS-Addressing, de overige diensten niet.
• StuurGBABericht kan in de proefomgeving getest worden. Voor sPoed zal een aparte testomgeving worden ingericht. sPoed werkt immers de database van GBA-V bij.

De dienst sPoed volgt in grote lijnen de sPd operaties: zie LO GBA IV.5.2. In het overzicht hieronder zijn sPd-operaties afgezet tegen de acties in sPoed. Als geen actie aanwezig is nvt opgenomen of wordt een korte toelichting gegeven.

Tabel 1. sPd protocol invulling in de sPoed dienst

Figuur 2. Structuur van een stuurGBAbericht (vraag)

Image

Figuur 3. Structuur van een stuurGBAbericht (antwoord)

Image

2. Voorbeelden van de stuurGBABericht webserivce

1. valideer_pl vraagbericht met Lg01 in CDATA sectie

Image

1. Het gbabericht bevat in dit geval een CDATA sectie met daarin het complete Lg01 bericht. De encodering van dit bericht is in Teletex ingebed in Unicode. Het gbabericht is een verplicht veld.
2. De actie is valideer_pl (let op: kleine letters en _ (underscore)) en is verplicht.
3. De aanleiding is facultatief. In dit geval is 'kwaliteitscontrole' opgenomen.
4. berichtnummer is Lg01. Dit is het berichtnummer zoals vermeld in het Logisch Ontwerp GBA. Let hier ook weer op hoofd- en kleine letters. berichtnummer is verplicht.

2. valideer_pl antwoord: BCM controle geslaagd: 1 of meer fouten gevonden

Image

1. Het antwoord op de vraag bevat een algemene resultaatcode voor de actie valideer_pl: pl_ok wanneer de validatie is doorlopen en er geen fouten/issues in de PL zijn ontdekt; pl_nok wanneer de validatie is doorlopen en er fouten/issues (1 of meer) zijn ontdekt of als de validatie niet succesvol is doorlopen. Als er fouten zijn ontdekt is er een sectie details met hierin voor elk van de issues een detail. Als de validatie niet succesvol is doorlopen is er een sectie details waarin een van de foutcodes is opgenomen (Zie LO GBA tabel C1 par C7.3.5).
2. De toelichting bevat bij pl_ok en pl_nok een vermelding van de naam en de versie van het systeem dat is gebruikt om de PL te valideren. In dit voorbeeld: BCM v4.3. Wanneer de resultaatcode een andere (fout)code bevat, dan bevat toelichting een tekstuele toelichting op deze code.
3. Wanneer de validatie is doorlopen en er fouten/issues in de PL zijn geconstateerd, dan bevat details 1 of meer detail elementen met elk een code en omschrijving. Het element details is facultatief en kan wanneer geen details gevonden zijn afwezig zijn (bij pl_ok, of bij fouten waardoor geen validatie van de PL heeft plaats kunnen vinden).
4. De code komt overeen met de code uit de BCM sheet. De code is altijd aanwezig binnen detail.
5. De omschrijving komt overeen met de code uit de BCM sheet. Het meegeven van een omschrijving is niet verplicht.
6. De referentie bevat de activiteit ID en is primair bedoeld om bij vragen aan RvIG het verzonden bericht terug te vinden.

3. valideer_pl antwoord: BCM controle geslaagd: geen fouten gevonden

Image

4. sPoed vraag: SummarizeMessages

Image

1. MessageID is aanwezig als leeg element. RelatesTo is niet van toepassing en niet verplicht volgens de WSDL, dus niet aanwezig (bij aanwezigheid wordt deze genegeerd).
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
3. Action is gevuld met de standaardwaarde "sPoed".
4. De actie is SummarizeMessages.

5. sPoed antwoord: SummarizeResult (0 of meerdere GBA-berichten gevonden)

Image

1. De MessageID is aanwezig (verplicht element), maar bevat geen waarde.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
3. Action is gevuld met de standaardwaarde "sPoed".
4. De resultaatcode is SummarizeResult bij het succesvol ophalen van een bericht (zoals beschreven in sPd protocol) en is case-sensitive.
5. Code is het aantal GBA-berichten die klaar staan ter verzending. omschrijving is niet aanwezig.
6. Referentie is gevuld met het GBA-V activiteit ID dat hoort bij de SummarizeMessages bevraging.

6. sPoed vraag: ListMessages

Image

1. MessageID is aanwezig als leeg element. RelatesTo is niet van toepassing en niet verplicht volgens de WSDL, dus niet aanwezig (bij aanwezigheid wordt deze genegeerd).
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
3. Action is gevuld met de standaardwaarde "sPoed".
4. De actie is ListMessages voor het bevragen welke GBA-berichten opgehaald kunnen worden (zoals beschreven in sPd protocol en is case-sensitive).

7. sPoed antwoord: ListMessagesResult (bij gevonden berichten)

Image

1. MessageID is aanwezig als leeg element. RelatesTo is niet van toepassing en niet verplicht volgens de WSDL, dus niet aanwezig (bij aanwezigheid wordt deze genegeerd).
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
3. Action is gevuld met de standaardwaarde "sPoed".
4. De resultaatcode is ListMessagesResult bij het succesvol ophalen van een bericht (zoals beschreven in sPd protocol en is case-sensitive).
5. Code is het GBA-berichtID van het op te vragen GBA-bericht. Voor elk gevonden bericht wordt een detail opgenomen met in code het GBA-berichtID van het GBA-bericht.
6. Rreferentie is gevuld met het activiteit ID dat hoort bij de ListMessages bevraging.

8. sPoed antwoord: ListMessagesConfirmation (GEEN gevonden GBA-berichten)

Image

1. MessageID is aanwezig als leeg element. RelatesTo is niet van toepassing en niet verplicht volgens de WSDL, dus niet aanwezig (bij aanwezigheid wordt deze genegeerd).
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
3. Action is gevuld met de standaardwaarde "sPoed".
4. De resultaatcode is ListMessagesConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij geen gevonden bericht(en) ter verzending.
5. Referentie is gevuld met het activiteit ID dat hoort bij de ListMessages bevraging.

9. sPoed vraag: GetMessage

Image

1. MessageID is aanwezig als leeg element. RelatesTo is niet van toepassing en niet verplicht volgens de WSDL, dus niet aanwezig (bij aanwezigheid wordt deze genegeerd).
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. Action is gevuld met de standaardwaarde sPoed.
4. De actie is GetMessage (zoals beschreven in sPd protocol en is case-sensitive) voor het ophalen van een bericht.
5. Het GBA-berichtID wordt in berichtnummer geplaatst.

10. sPoed antwoord: GetMessageResult met daarin een GBA-bericht als dat bericht geen reactie is op een eerder bericht (eerste bericht in een GBA-berichtencyclus)

Image

1. MessageID is het GBA-berichtID, toegekend door het GBA-V systeem. RelatesTo is niet aanwezig omdat dit het eerste bericht is in de berichtencyclus.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. Action is gevuld met de standaardwaarde sPoed.
4. De resultaatcode is GetMessageResult (zoals beschreven in sPd protocol en is case- sensitive) bij het succesvol ophalen van een bericht.
5. gbabericht bevat het complete Lq01 bericht.
6. berichtnummer is in dit voorbeeld Lq01. Het is een berichtnummer zoals vermeld in het Logisch Ontwerp. Het berichtnummer is gelijk aan het berichtnummer genoemd in het werkelijke bericht in gbabericht.
7. referentie is gevuld met het activiteit ID dat hoort bij de GetMessage bevraging.

11. sPoed antwoord: GetMessageResult met daarin een GBA-bericht als dat bericht een reactie is op een eerder bericht (vervolgbericht in een GBA-berichtencyclus)

Image

1. MessageID is het GBA-berichtID, toegekend door het GBA-V systeem.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. RelatesTo is gevuld met het MessageID van het bericht waar, in dit voorbeeld, de Pf01 in dit bericht het antwoord op is. De MessageID komt uit MessageID van bijvoorbeeld een PutMessage met een Lg01. De MessageID van dat bericht was in dit voorbeeld 23456.
4. Action is gevuld met de standaardwaarde sPoed.
5. De resultaatcode is GetMessageResult (zoals beschreven in sPd protocol en is case- sensitive) bij het
succesvol ophalen van een bericht.
6. gbabericht bevat het complete Pf01 bericht.
7. berichtnummer is Pf01. Dit is het berichtnummer zoals vermeld in het Logisch Ontwerp GBA-V. Let hier ook weer op hoofd- en kleine letters.
8. referentie is gevuld met het activiteit ID dat hoort bij de GetMessage bevraging.

12. sPoed antwoord: GetMessageConfirmation (GBA-bericht niet gevonden)

Image

1. MessageID en RelatesTo zijn niet van toepassing: de GetMessageConfirmation bevat geen bericht.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. Action is gevuld met de standaardwaarde sPoed.
4. De resultaatcode is GetMessageConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij niet kunnen ophalen van een bericht.
5. referentie is gevuld met het activiteit ID dat hoort bij de GetMessage bevraging.

13. sPoed vraag: PutMessage met La01 in CDATA sectie

Image

1. MessageID is gevuld met het ID van het, in dit voorbeeld La01, bericht.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. RelatesTo is in dit voorbeeld gevuld met het GBA-berichtID. Deze komt uit MessageID van het webservice bericht waarin het GBA vraagbericht (in dit geval Lq01) was opgenomen. In dit voorbeeld had dit sPoed antwoord: GetMessageResult met daarin het GBA-bericht (eerste bericht in de cyclus)
kunnen zijn.
4. Action is gevuld met de standaardwaarde sPoed.
5. gbabericht bevat in dit geval een CDATA sectie met daarin het complete La01 bericht. De encodering van het bericht in dit voorbeeld is Teletex ingebed in Unicode.
6. De actie is PutMessage (zoals beschreven in sPd protocol en is case-sensitive) voor het versturen van
een bericht.
7. berichtnummer is La01. Dit is het berichtnummer zoals vermeld in het Logisch Ontwerp GBA-V. Let hier ook weer op hoofd- en kleine letters. berichtnummer is verplicht bij de actie PutMessage en is overeenkomstig met het berichtnummer in het GBA-bericht.

14. sPoed antwoord: PutMessageConfirmation (Bevestiging bericht is ontvangen).

Image

1. MessageID en RelatesTo zijn niet van toepassing: de PutMessageConfirmation bevat geen bericht.
2. Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
3. Action is gevuld met de standaardwaarde sPoed.
4. De resultaatcode is PutMessageConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij het succesvol plaatsen van een bericht.
5. referentie is gevuld met het activiteit ID dat hoort bij de PutMessage bevraging.

15. actie ECHO: stuurGBABerichtRequest

Image

1.  De vaste tekst GBA-BERICHT.
2. De actie ECHO (let op: hoofdletters).
3. De aanleiding is een vrij in te vullen tekst in stuurGBABerichtRequest. De aanleiding wordt zonder verandering teruggestuurd in het antwoordbericht.
4. Het berichtnummer is een vrij in te vullen berichtnummer. Ook dit berichtnummer wordt onveranderd in het antwoord teruggestuurd.

16. actie ECHO: Antwoord op bovenstaand bericht

Image

1. De resultaatcode van een valide ECHO stuurGBABerichtRequest is altijd OK (voorwaarde: er treedt geen technische fout op).
2. De toelichting bij de resultaatcode is Echo Response.
3. In details worden de aanleiding, actie, het berichtnummer en het in de vraag meegestuurde bericht zoals gegeven in de vraag mee terug teruggestuurd.
4. Referentie wordt standaard gevuld met de Activiteit-ID (ter referentie RvIG).

17. Technische fout

Image

De request kan om verschillende redenen worden afgekeurd. In bovenstaand voorbeeld gaat het om een technische fout. Andere mogelijkheden zijn:

• Ongeldige combinatie gebruikersnaam / wachtwoord
• Server is niet geactiveerd voor dit account
• Wachtwoord verlopen
• Geen actuele autorisatietabelregel
• Ongeldige waarde voor parameter

Zie voor een opsomming van de foutcodes LO GBA tabel C1 par C7.3.5).

18. SOAP fout opbouw
 

Image

Appendix A: opbouw en tekst-encodering van <gbabericht>

Er zijn twee varianten van de inhoud van <gbabericht>: een met het bericht in een CDATA sectie en een met het GBA-bericht opgenomen als tekst in de XML. Van beide varianten volgt hieronder een voorbeeld.

element gbabericht met Lg01 in CDATA sectie

Image

① Het gbabericht bevat in dit geval een CDATA sectie met daarin het complete Lg01 bericht. De encodering van dit bericht is in Teletex ingebed in Unicode. Het bericht is een verplicht veld.

Elk bericht dat wordt meegegeven in de XML is in Teletex gerepresenteerd door UTF-8 unicode. Om van het Teletex bericht te komen tot het juiste bericht in de XML worden de volgende stappen doorlopen:
1.Teletex tekens worden geëncodeerd met Teletex bytes.
2.Elke Teletex byte wordt gepresenteerd met (c.q. vervangen door) een Unicode teken op basis van de numerieke waarde.
3.De resulterende Unicode tekens worden geëncodeerd en getransporteerd als UTF-8. Stap 3 is standaard voor webservices. Van belang zijn stap 1 en 2.

Image

Je ziet dit terug in het eerder gegeven XML bericht hierboven.

Het is mogelijk de Lg01 als tekst met gewone markup mee te sturen in plaats van in een CDATA sectie. Let er hierbij op dat de volgende karakters vervangen worden door XML escape karakters (character/entities):

XML character entities

Image

Strikt genomen hoeven alleen & en < vervangen te worden, maar het is goed gebruik al deze karakters te vervangen. Een Carriage Return komt in GBA-berichten zelden voor en is een speciaal geval. Een CR moet altijd worden opgenomen als &#13; en kan niet worden gebruikt in een CDATA sectie. De meest veelzijdige vorm van het versturen van een bericht, waarbij ook rekening wordt gehouden met Carriage Returns, is hiermee het meesturen van de PL als elementinhoud (zonder CDATA) en het escapen van alle hierboven genoemde karakters. Wanneer geen carriage return in het bericht staat is de eenvoudigste vorm die met de CDATA sectie (zonder character references).

Het Teletex karakter voor Form Feed (FF) kan niet worden gebruikt in deze webservice. Ook de character reference #12; is niet toegestaan. Dit Teletex karakter wordt in de praktijk niet gebruikt en vormt dus geen praktische belemmering.

Het element gbabericht met de Lg01 als tekst

Image

In dit voorbeeld is de ampersand in de straatnaam V&D weg vervangen door &amp;.

Appendix B: WSDL en XSD

stuurGBABericht-v1.0.wsdl

Image

Image

Het element <wsaw:UsingAddressing wsdl:required="true" /> betekent dat WS-Addressing verplicht is. Het systeem bepaalt echter aan de hand van welke dienst gebruikt wordt of de WS-Addressing van toepassing is. Voor de Controleren PL en de ECHO
diensten is WS-Addressing NIET verplicht.

De inhoud van de berichten voldoet aan het volgende schema:
XSD voor stuurGBABerichtRequest en stuurGBABerichtResponse

Image

Image

Image