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>

Op deze pagina

1 Opbouw interface
- 1.1 Verzoek
  - 1.1.1 Context
  - 1.1.2 Vragen
- 1.2 Repliek
  - 1.2.1 Repliek/Context
  - 1.2.2 Repliek/Antwoorden
  - 1.2.3 Repliek/Uitzonderingen

Verbonden pagina’s

Handleidingen per dienst

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
		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.

MAGDA Gebruikersomgeving

Opbouw interface MAGDA SOAP webservices