Toelichting en voorbeelden wsdl stuurGBAbericht
Wat kunt u vinden op deze pagina?
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
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
| sPd-commando | sPoed-webservice commando |
| LogonRequest | Webservice authenticatie |
| LogonConfirmation | Webservice authenticatie foutafhandeling |
| LogoffRequest | nvt, impliciet na ontvangen webservice response-bericht |
| LogoffConfirmation | nvt |
| PutMessage | PutMessage |
| PutMessageConfirmation | PutMessageConfirmation |
| GetMessage | GetMessage |
| GetMessageResult | GetMessageResult |
| GetMessageConfirmation | GetMessageConfirmation |
| DeleteMessages | nvt |
| DeleteMessagesConfirmation | nvt |
| ListMessages | ListMessages |
| ListMessagesResult | ListMessagesResult |
| ListMessagesConfirmation | ListMessagesConfirmation |
| SummarizeConfirmation | nvt: fouten bij het retourneren van een geldig antwoord zijn altijd een 'technische fout'. |
| ChangePasswordRequest | webservice change password |
| ChangePasswordConfirmation | webservice change password |
| NoOperationConfirmation | nvt |
Figuur 2 Structuur van een stuurGBAbericht (vraag)
Figuur 3 Structuur van een stuurGBAbericht (antwoord)
2. Voorbeelden van de stuurGBABericht webserivce
1. valideer_pl vraagbericht met Lg01 in CDATA sectie
Datum
14 juni 2019
① 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.
② De actie is valideer_pl (let op: kleine letters en _ (underscore)) en is verplicht.
③ De aanleiding is facultatief. In dit geval is 'kwaliteitscontrole' opgenomen.
④ 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
Datum
14 juni 2019
① 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).
② 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.
③ 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).
④ De code komt overeen met de code uit de BCM sheet. De code is altijd aanwezig binnen detail.
⑤ De omschrijving komt overeen met de code uit de BCM sheet. Het meegeven van een omschrijving is niet verplicht.
⑥ De referentie bevat de activiteit ID en is primair bedoeld om bij vragen aan RvIG het verzonden bericht terug te vinden.
Datum
14 juni 2019
3. valideer_pl antwoord: BCM controle geslaagd: geen fouten gevonden
Datum
14 juni 2019
4. sPoed vraag: SummarizeMessages
Datum
14 juni 2019
① 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).
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
③ Action is gevuld met de standaardwaarde "sPoed".
④ De actie is SummarizeMessages.
5. sPoed antwoord: SummarizeResult (0 of meerdere GBA-berichten gevonden)
Datum
14 juni 2019
① De MessageID is aanwezig (verplicht element), maar bevat geen waarde.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
③ Action is gevuld met de standaardwaarde "sPoed".
④ De resultaatcode is SummarizeResult bij het succesvol ophalen van een bericht (zoals beschreven in sPd protocol) en is case-sensitive.
⑤ code is het aantal GBA-berichten die klaar staan ter verzending. omschrijving is niet aanwezig.
⑥ referentie is gevuld met het GBA-V activiteit ID dat hoort bij de SummarizeMessages bevraging.
6. sPoed vraag: ListMessages
Datum
14 juni 2019
① 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).
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
③ Action is gevuld met de standaardwaarde "sPoed".
④ 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)
Datum
14 juni 2019
① 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).
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
③ Action is gevuld met de standaardwaarde "sPoed".
④ De resultaatcode is ListMessagesResult bij het succesvol ophalen van een bericht (zoals beschreven in sPd protocol en is case-sensitive).
⑤ 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.
⑥ referentie is gevuld met het activiteit ID dat hoort bij de ListMessages bevraging.
8. sPoed antwoord: ListMessagesConfirmation (GEEN gevonden GBA-berichten)
Datum
14 juni 2019
① 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).
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard waarde.
③ Action is gevuld met de standaardwaarde "sPoed".
④ De resultaatcode is ListMessagesConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij geen gevonden bericht(en) ter verzending.
⑤ referentie is gevuld met het activiteit ID dat hoort bij de ListMessages bevraging.
9. sPoed vraag: GetMessage
Datum
14 juni 2019
① 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).
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ Action is gevuld met de standaardwaarde sPoed.
④ De actie is GetMessage (zoals beschreven in sPd protocol en is case-sensitive) voor het ophalen van een bericht.
⑤ 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)
Datum
14 juni 2019
① MessageID is het GBA-berichtID, toegekend door het GBA-V systeem. RelatesTo is niet aanwezig omdat dit het eerste bericht is in de berichtencyclus.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ Action is gevuld met de standaardwaarde sPoed.
④ De resultaatcode is GetMessageResult (zoals beschreven in sPd protocol en is case- sensitive) bij het succesvol ophalen van een bericht.
⑤ gbabericht bevat het complete Lq01 bericht.
⑥ 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.
⑦ 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)
Datum
14 juni 2019
① MessageID is het GBA-berichtID, toegekend door het GBA-V systeem.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ 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.
④ Action is gevuld met de standaardwaarde sPoed.
⑤ De resultaatcode is GetMessageResult (zoals beschreven in sPd protocol en is case- sensitive) bij het
succesvol ophalen van een bericht.
⑥ gbabericht bevat het complete Pf01 bericht.
⑦ berichtnummer is Pf01. Dit is het berichtnummer zoals vermeld in het Logisch Ontwerp GBA-V. Let hier ook weer op hoofd- en kleine letters.
⑧ referentie is gevuld met het activiteit ID dat hoort bij de GetMessage bevraging.
12. sPoed antwoord: GetMessageConfirmation (GBA-bericht niet gevonden)
Datum
14 juni 2019
① MessageID en RelatesTo zijn niet van toepassing: de GetMessageConfirmation bevat geen bericht.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ Action is gevuld met de standaardwaarde sPoed.
④ De resultaatcode is GetMessageConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij niet kunnen ophalen van een bericht.
⑤ referentie is gevuld met het activiteit ID dat hoort bij de GetMessage bevraging.
13. sPoed vraag: PutMessage met La01 in CDATA sectie
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa= "http://www.w3.org/2005/08/addressing">
<soap:Header>
<wsa:MessageID>urn:brp:spd:messageid:394857345</wsa:MessageID> ①
<wsa:ReplyTo>http://www.w3.org/2005/08/addressing/anonymous</wsa:ReplyTo> ②
<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To> ②
<wsa:RelatesTo>urn:brp:spd:messageid:199886546579</wsa:RelatesTo> ③
<wsa:Action>sPoed</wsa:Action> ④
</soap:Header>
<soap:Body>
<stuurGBABerichtRequest xmlns="http://www.rvig.nl/GBA/GBA-V/stuurGBABericht-v1.0">
<gbabericht>
<![CDATA[00000000La0120050518143000000808638040700000000000036101129011001080863804070 1200093016719280210008MAaÄika0240009VIulðovAa03100080000000003200040000033000400008310
006010300832000819941001040098230002PK04020051000400388230002PK040098230002PK04048051
000400018230002PK831000604000083200081994031004020051000400278230002PK070087010001008
078091000405181010001W1030008199005011110007V&Dweg11200025111600062712HW7210001A]]>
</gbabericht>⑤
<actie>PutMessage</actie>⑥
<berichtnummer>La01</berichtnummer>⑦
</stuurGBABerichtRequest>
</soap:Body>
</soap:Envelope>
Datum
14 juni 2019
① MessageID is gevuld met het ID van het, in dit voorbeeld La01, bericht.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ 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.
④ Action is gevuld met de standaardwaarde sPoed.
⑤ 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.
⑥ De actie is PutMessage (zoals beschreven in sPd protocol en is case-sensitive) voor het versturen van
een bericht.
⑦ 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.
Datum
14 juni 2019
14. sPoed antwoord: PutMessageConfirmation (Bevestiging bericht is ontvangen).
Datum
14 juni 2019
① MessageID en RelatesTo zijn niet van toepassing: de PutMessageConfirmation bevat geen bericht.
② Vanwege de synchrone communicatie is de binding anoniem en is dit de standaard- waarde.
③ Action is gevuld met de standaardwaarde sPoed.
④ De resultaatcode is PutMessageConfirmation (zoals beschreven in sPd protocol en is case- sensitive) bij het succesvol plaatsen van een bericht.
⑤ referentie is gevuld met het activiteit ID dat hoort bij de PutMessage bevraging.
15. actie ECHO: stuurGBABerichtRequest
Datum
14 juni 2019
① De vaste tekst GBA-BERICHT.
② De actie ECHO (let op: hoofdletters).
③ De aanleiding is een vrij in te vullen tekst in stuurGBABerichtRequest. De aanleiding wordt zonder verandering teruggestuurd in het antwoordbericht.
④ 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
Datum
14 juni 2019
① De resultaatcode van een valide ECHO stuurGBABerichtRequest is altijd OK (voorwaarde: er treedt geen technische fout op).
② De toelichting bij de resultaatcode is Echo Response.
③ In details worden de aanleiding, actie, het berichtnummer en het in de vraag meegestuurde bericht zoals gegeven in de vraag mee terug teruggestuurd.
④ <referentie> wordt standaard gevuld met de Activiteit-ID (ter referentie RvIG).
17. Technische fout
Datum
14 juni 2019
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
Datum
14 juni 2019
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
Datum
14 juni 2019
① 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.
Datum
14 juni 2019
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
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 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  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
In dit voorbeeld is de ampersand in de straatnaam V&D weg vervangen door &.
Appendix B: WSDL en XSD
stuurGBABericht-v1.0.wsdl
Datum
14 juni 2019
Datum
14 juni 2019
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
Datum
14 juni 2019
type="xsd:string" minOccurs="0" maxOccurs="1" />
<xsd:element ref="details"
minOccurs="0" maxOccurs="1" />
<xsd:element name="gbabericht" type="gbaberichtType" minOccurs="0" maxOccurs="1" />
<xsd:element name="berichtnummer" type="xsd:string"
minOccurs="0" maxOccurs="1" />
<xsd:element name="referentie" type="xsd:string" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="details" nillable="true">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="detail"
minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="detail">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="code" type="xsd:string" minOccurs="1" maxOccurs="1" />
Datum
14 juni 2019
Datum
14 juni 2019
