Document toolboxDocument toolbox


DIGITAAL VLAANDEREN

Opbouw interface MAGDA SOAP webservices

 

Opbouw interface

Elke MAGDA 2.0 webservice is op eenzelfde manier opgebouwd, zowel voor het Verzoek als voor Repliek en zelfs Uitzonderingen. Dit is het MAGDA 2.0 canoniek model. Dit maakt het voor de afnemer eenvoudiger MAGDA -diensten te implementeren. 

Verzoek

Het request bericht bevat steeds een <Verzoek> element dat bestaat uit 2 elementen:

  • <Context>

  • <Vragen>

Het <Vragen> element bevat een <Vraag> element met op zijn beurt 2 onderliggende elementen:

  • <Referte>

  • <Inhoud>

Context

Het Context element dat structureel identiek is voor de verschillende MAGDA diensten zal in eerste instantie voor autorisatie doeleinden aangewend worden, en in tweede instantie om Request en Reponse ketting te kunnen correleren. Afhankelijk van de afnemer en de dienst die men wenst op te roepen, moet de Context op een verschillende wijze ingevuld worden.

 

Element Context/

Cardinaliteit

Omschrijving

Element Context/

Cardinaliteit

Omschrijving

Naam

Verplicht

Bevat de naam van de dienst die wordt aangevraagd of waarvoor er een antwoord beschikbaar is. De naam in dit element wordt gevalideerd tegenover de “geprogrammeerde” naam. De dienstnaam is terug te vinden in de dienstspecifieke documentatie.

Vb: Persoon.GeefPersoon, Onderneming.GeefOnderneming, …

Versie

Verplicht

Bevat het versienummer van de dienst die wordt aangevraagd. Het opgegeven versienummer moet overeenkomen met de “geprogrammeerde” versie. De versie is terug te vinden in de dienstspecifieke documentatie. 

Formaat: <Hoofdnummer>.<Bijnummer>.<Buildnummer>

Vb: 02.00.0000

Bericht

 

 

 

Type

Verplicht

het bericht type moet "VRAAG" zijn. Functioneel wordt er gevalideerd dat er voor een vraag/antwoord wel degelijk VRAAG opgegeven wordt en niet ANTWOORD of DATAGRAM.

 

Tijdstip

Verplicht

Dit is het tijdstip (datum en uur) waarop de boodschap overhandigd werd aan/door MAGDA. Er wordt geen functionele validatie uitgevoerd op de datum en het tijdstip, wel een technische en dit op de vorm van de datum en het tijdstip.

 

 

Datum

 

Formaat: yyyy-mm-dd
Vb: 2006-05-12

 

 

Tijd

 

Formaat: HH:mm:ss.sss
Vb: 16:15:11.435

 

Afzender

 

 

 

 

Identificatie

Verplicht

Bevat de URI van de afnemer. Deze moet overeenkomen met de URI gekoppeld aan de dienst/versie in de MAGDA administratiedatabank (VIPADM). Komt het niet overeen met de configuratie in VIPADM wordt er een Uitzondering aangemaakt.

Deze URI wordt verkregen tijdens het aansluitingsproces.

 

 

Naam

Optioneel

Bevat de naam van de afzender. De afnemer is vrij een naam te kiezen.

 

 

Referte

Verplicht

Bevat een waarde die elke boodschap uniek identificeert. Geprefereerd wordt met een UUID van 36 lang gewerkt. 

 

 

OrganisatieEenheid

Optioneel

De OrganisatieEenheid of “Instrumenterende Overheid” is een niveau van toepassingscategorisatie. Het is immers mogelijk dat meerdere organisatie-eenheden eenzelfde toepassing gebruiken op een MAGDA dienst te benaderen. Op dit moment wordt dit niet gebruikt binnen MAGDA.

 

 

Hoedanigheid

Verplicht/optioneel

De hoedanigheid bepaalt in welk kader - met welke reden - de dienst bevraagd wordt.

Deze hoedanigheid wordt verkregen tijdens het aansluitingsproces.

Afhankelijk van de dienst die opgevraagd wordt is dit veld verplicht of dient dit veld weggelaten te worden. Als u een dienst wilt bevragen met (gevoelige) persoonsgegevens dient u een hoedanigheid mee te geven. In dit geval zal u een hoedanigheid ontvangen tijdens uw aansluiting. Voor diensten zonder persoonsgegevens (voornamelijk de diensten onder het domein ondernemingen) mag er geen hoedanigheid mee gegeven worden.

 

 

Gebruiker

Optioneel

Mag niet aanwezig zijn in de Vraag.

 

Ontvanger

Optioneel

Optioneel element. Mag integraal weggelaten worden in de request.

 

 

Identificatie

Verplicht

Indien het Ontvanger element wordt ningevuld moet volgens de MAGDA richtlijnen dit steeds “vip.vlaanderen.be” zijn.

 

 

Naam

Optioneel

Optioneel element. Mag weggelaten worden

 

 

Referte

Optioneel

Niet opgeven in het verzoek.

 

 

OrganisatieEenheid

Optioneel

Niet opgeven in het verzoek.

 

 

Hoedanigheid

Optioneel

Niet opgeven in het verzoek.

 

 

Gebruiker

Optioneel

Niet opgeven in het verzoek.

Annotaties

Optioneel

Niet opgeven in het verzoek.

<Context> <Naam>GeefBewijs</Naam> <Versie>02.00.0000</Versie> <Bericht> <Type>VRAAG</Type> <Tijdstip> <Datum>2011-03-08</Datum> <Tijd>08:38:12.222</Tijd> </Tijdstip> <Afzender> <Identificatie>***URI***</Identificatie> <Referte>550e8400-e29b-41d4-a716-446655440000</Referte> <Hoedanigheid>***HC***</Hoedanigheid> </Afzender> <Ontvanger> <Identificatie>vip.vlaanderen.be</Identificatie> <Naam>VIP</Naam> </Ontvanger> </Bericht> </Context>

Vragen

Element

Cardinaliteit

Omschrijving

Element

Cardinaliteit

Omschrijving

Vraag

 

 

 

Referte

Verplicht

Een unieke referte per vraag. Geprefereerd is dit een UUID van 36 lang. Daar een webservice oproep maar één Vraag-element toelaat, is het toegestaan dat de vraagreferte identiek is aan de referte opgegeven in in Afzender/Referte.

 

Inhoud

Verplicht

De feitelijk vraag van de webservice. Dit kan ook een registratie zijn, of verwijdering van gegevens, ... .

Repliek

Een webservice kan twee soorten antwoorden teruggeven:

  • of een SOAPFault.

  • of een Repliek (al dan niet met Uitzonderingen).

Voor meer informatie rond de foutafhandeling van een MAGDA 2.0 webservice wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.

Enkel de Repliek wordt op deze pagina besproken.

Ontvangt de afnemer een Repliek dan zal de opbouw van een XML als volgt er uit zien:

Repliek/Context

De Context bij een Repliek zal op een volgende manier opgebouwd worden:

Element Context/

Omschrijving

Naam

Naam van de dienst Vb Persoon.GeefPersoon

Versie

Versie van de dienst Vb 02.00.0000

Bericht

 

 

Type

“ANTWOORD”

 

Tijdstip

Datum en tijdstip van aanmaak antwoord

 

Afzender

Opmerkingen uit Analyse space toevoegen

 

 

Identificatie

vaste waarde “vip.vlaanderen.be”

 

 

Naam

vaste waarde “MagdaGateway“

 

 

Referte

Dit is de MAGDA VIPDialoogcode, een unieke code binnen MAGDA ter identificatie van elke request - response flow. Deze is onder de vorm van een UUID, 36 lang.

 

 

OrganisatieEenheid

Zal niet aanwezig zijn

 

 

Hoedanigheid

Zal niet aanwezig zijn

 

 

Gebruiker

Zal niet aanwezig zijn

 

Ontvanger

 

 

 

Identificatie

Zoals doorgestuurd in Afzender/Identificatie in de vraag

 

 

Naam

Zoals doorgestuurd in Afzender/Identificatie in de vraag

 

 

Referte

Zoals doorgestuurd in Afzender/Identificatie in de vraag. Zo kunnen het vraag- en antwoordbericht aan elkaar gelinkt worden indien dit element voor elek vraag uniek is.

 

 

OrganisatieEenheid

Zal niet aanwezig zijn

 

 

Hoedanigheid

Zoals doorgestuurd in Afzender/Identificatie in de vraag

 

 

Gebruiker

Zal niet aanwezig zijn

Annotaties

Wordt standaard niet ingevuld. Indien dit gebruikt wordt, zal dit expliciet vermeld worden in de handleiding van de dienst.

Repliek/Antwoorden

Na verwerking wordt een <Antwoorden><Antwoord>-element aangemaakt met hierin

  • Het Referte-element

  • Een Inhoud- en/of Uitzonderingen-element

Het Referte-element is de waarde van het Vraag/Referte-element zoals doorgestuurd in de request. Op deze manier kunnen vraag en antwoord aan elkaar gelinkt worden. Of al dan niet een Inhoud en/of Uitzondering-element aangemaakt wordt is afhankelijk van de verwerking.

Een Inhoud-element wordt gezet indien de verwerking succesvol verlopen is. Er zijn bijvoorbeeld

  • Gegevens gevonden op basis van de sleutel;

  • Gegevens gevonden op basis van verschillende zoekcriteria;

  • Of de registratie van gegevens is geslaagd.

Het Inhoud-element bevat voornamelijk de gegevens die gevraagd werden, denk maar aan de Persoon, of een (LED)Bewijs. Bij een registratie kan die ook een Resultaat-element bevatten die de status van verwerking aangeeft. Het Inhoud-element is dienstspecifiek: Handleidingen dienstenaanbod .

Een Uitzondering-element (kan in combinatie met een Inhoud-element) indien een fout heeft plaatsgevonden, dit kan een functionele, businessfout zijn of een waarschuwing.

Functionele fouten zijn bijvoorbeeld:

  • Ongeldig INSZ

  • Ongeldig ondernemingsnummer

  • Niet bestaande postcode

  • …. .

Onder businessfouten wordt specifieke businesslogica bedoeld die gevalideerd moet worden, voor of tijdens de verwerking van de gegevens. Ook deze businesslogica kan een uitzondering aanmaken. Veel businessfouten zijn vertalingen van fouten die door de bron worden teruggegeven; zij zijn tenslotte de houders van de meeste businesslogica.

Al deze fouten resulteren in een Uitzondering (of meerdere) op niveau 3, dus onder Antwoord. Voor meer informatie met betrekking tot de werking van Uitzonderingen wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.

Repliek/Uitzonderingen

De uitzonderingen op dit niveau hebben veelal betrekking op autorisatiefouten. Voor meer informatie rond de Uitzonderingen op Repliek van een MAGDA 2.0 webservice wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.


Voor vragen of opmerkingen kan u de MAGDA helpdesk contacteren

De MAGDA Gebruikersomgeving is een officiële website van de Vlaamse overheid

uitgegeven door Digitaal Vlaanderen