Elke MAGDA 2.0 webservice is niet enkel als een SOAP te benaderen maar ook door middel van een bestand. Dit bestand bevat één tot meerdere vragen die dan achterliggend door de webservice verwerkt zullen worden. Het resultaat van de verwerking verkrijgt men eveneens als bestand aangeleverd.

Informatie:

Belangrijk is dat bij de aanvraag tot toegang van het MAGDA platform vermeld wordt dat gebruik gemaakt zal worden van bestanden voor het bevragen van de webservices. Aan de kant van MAGDA moet namelijk bijkomende configuratie gebeuren alsook een FTP-folder toegekend worden (indien de afnemer nog geen folder heeft).

Algemeen

Service XSD

Om een bestand aan te maken wordt de Service folder gebruikt die meegeleverd wordt in het XSD zip-bestand van de webservice. Er kan bijgevolg enkel met xml-bestanden gewerkt worden die conform zijn aan de MAGDA-standaarden. Andere formaten zijn niet mogelijk.

De Service folder bestaat uit twee XSD-bestanden namelijk een XSD voor de vraag en een Reponse XSD voor het antwoord.

Informatie:

Het overzicht van de XSD is terug te vinden op: Overzicht endpoints en XSD's.

FTP folder

Wenst de afnemer de webservices via batch te bevragen, dan verkrijgt deze tijdens het aansluitingsproces een FTP-folder. De afnemer toepassing plaatst de vraagbestanden in de To_Vip folder. MAGDA zal dat bestand binnen een bepaalde tijd detecteren (op basis van een voorgedefinieerd benamingspatroon), oppikken en verwerken. Het bestand zal dan eerst worden gekopieerd naar de cache/to_vip folder en daarna worden doorgegeven naar de MAGDA verwerkingsomgeving. Na verwerking door MAGDA komt het antwoordbestand in de From_Vip folder terecht.

Voor meer informatie betreffende de MAGDA FTP omgeving en geldende richtlijnen wordt verwezen naar de pagina Richtlijnen FTP-gebruik.

Bestandsnaam

Elke webservice kent zijn eigen prefix wat betreft de bestandsnamen. De bestandsnaam per webservice is beschikbaar in de diensthandleiding: Handleidingen dienstenaanbod.

De prefix is van belang opdat MAGDA weet welke bestanden door welke webservice uitgevoerd moet worden.

Na de prefix moet de bestandsnaam aangevuld met datum en tijdstip (tot op miliseconden). Het is toegelaten om in de bestandsnaam ook een intern volgnummer of andere identificaties toe te voegen.

Belangrijk is wel dat elk aangeboden bestand een unieke bestandsnaam moet hebben. De bestanden mogen ook in een .zip aangeleverd worden.

Voorbeeld prefix: Persoon.GeefPersoon-0200_2014090518150_0001.xml

Opbouw vraag bestand

In 1 vraagbestand mogen maximaal 1000 vragen opgenomen worden.

De vraag XSD binnen de Service folder is op dezelfde manier opgebouwd als deze voor de Webservice maar laat wel meerdere Vraag-elementen toe. Hierdoor is het mogelijk om meerdere vragen te bundelen in één bestand en is het niet nodig om voor elke vraag een bestand aan te maken.

In de Vraag XSD identificeren we twee delen:

Context: bevat service onafhankelijke elementen
Vragen: bevat de service afhankelijke elementen.

Voorbeeld: de Service vraag XSD van de GeefPersoon service

Merk in bovenstaande afbeelding op dat het Vraagelement een kardinaliteit heeft van 1 tot ∞ en niet 1..1 zoals bij de webservice XSD.

Binnen het Context-segement worden de afnemerparameters opgenomen ter identificatie. Onderstaande tabel duidt aan welke gegevens binnen Context ingevuld moeten worden en met welke waardes.

Element	Inhoud

Element	Inhoud
Naam	Dienstnaam, exclusief het versienummer. Bijvoorbeeld “GeefPersoon”.
Versie	Versie van de dienst in formaat xx.xx.xxxx, bijvoorbeeld 02.00.0000
Type	Steeds “VRAAG”
Tijdstip/Datum	Datum van aanmaak bestand onder de vorm van yyyy-mm-dd.
Tijdstip/Tijd	Tijdstip van aanmaak bestand onder de vorm van hh:mm:ss.sss
Afzender/Identificatie	De URI die men verkregen heeft tijdens het toelatingsproces tot het MAGDA platform
Afzender/Naam	Naam van de (overheids)dienst.
Afzender/Referte	Unieke referte, de referte moet uniek zijn over al de door de afnemer aangeleverde bestanden. De vragen gesteld door de afnemer kunnen namelijk verspreid zijn over meerdere bestanden. Dit is geprefereerd een UUID van 36 lang., voorbeeld d32a4a2f-6353-47fb-9563-594fbed1ebd4.
Afzender/Hoedanigheid	Indien van toepassing: de hoedanigheidscode die men verkregen heeft tijdens het toelatingsproces tot het MAGDA platform
Ontvanger/Identificatie	Steeds “vip.vlaanderen.be”

Voorbeeld

<Context>
	<Naam>GeefPersoon</Naam>
	<Versie>02.00.0000</Versie>
	<Bericht>
		<Type>VRAAG</Type>
		<Tijdstip>
			<Datum>2014-07-09</Datum>
			<Tijd>03:07:24.000</Tijd>
		</Tijdstip>
		<Afzender>
			<Identificatie>***URI***</Identificatie>
			<Naam>DHO</Naam>
			<Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
			<Hoedanigheid>***HC***</Hoedanigheid>
		</Afzender>
		<Ontvanger>
			<Identificatie>vip.vlaanderen.be</Identificatie>
		</Ontvanger>
	</Bericht>
</Context>

Binnen het Vraag-element bevindt zich de uiteindelijke vraag. Het is mogelijk om meerdere Vraag-elementen op te geven, in feite oneindig. Al wordt aangeraden om het aantal Vraag-elementen beperkt te houden, bvb tot 1000. Kleinere bestanden zijn namelijk sneller verwerkt.

Binnen het Vraag-element bevinden zich

Referte
Inhoud

Voorbeeld

<Vragen>
	<Vraag>
		<Referte>219cd2a7-41ad-4de4-944d-5e5a1c7d1ba3</Referte>
		<Inhoud>
			<Criteria>
				<INSZ>11122255587</INSZ>
			</Criteria>
			<Bron>RR</Bron>
			<Taal>nl</Taal>
		</Inhoud>
	</Vraag>
	<Vraag>
		<Referte>cc70bfa0-1de5-4b13-9ba1-bd3553adfffd</Referte>
		<Inhoud>
			<Criteria>
				<INSZ>11223366554</INSZ>
			</Criteria>
			<Bron>SOA</Bron>
			<Taal>nl</Taal>
		</Inhoud>
	</Vraag>
</Vragen>

De Referte binnen het Vraag-element moet uniek zijn voor al de Vraag-elementen, dus niet enkel in dit bestand maar eventueel ook in andere door de afnemer aangeboden bestanden of webservice oproepen. Idealiter wordt een datum/tijdstip gebruikt, al wordt een UUID van 36 geprefereerd verkozen.

De Inhoud is afhankelijk van de webservice die aangeroepen wordt. Hiervoor wordt verwezen naar de gebruikershandleiding de dienst specifieke handleidingen, te vinden op Handleidingen dienstenaanbod.

Opbouw antwoord bestand

Eens het vraagbestand verwerkt is verkrijgt de afnemer in de From_vip het antwoordbestand. Dit bestand bevat op zich weer een Context alsook de Antwoorden. Het bestand kan ook Uitzonderingen bevatten. De afnemer verkrijgt geen melding als een bestand beschikbaar is! De afnemer moet zelf op regelmatige tijdstippen controleren op de aanwezigheid van een bestand.

Voorbeeld: de antwoord XSD van de GeefPersoon service.

De Context in het antwoord is in feite een spiegelbeeld van de Context in de vraag.

Element	Inhoud

Element	Inhoud
Naam	Dienstnaam
Versie	Versie van de dienst
Type	Steeds “ANTWOORD”
Tijdstip/Datum	Datum van aanmaak antwoordbestand onder de vorm van yyyy-mm-dd.
Tijdstip/Tijd	Tijdstip van aanmaak antwoordbestand onder de vorm van hh:mm:ss.sss
Afzender/Identificatie	“vip.vlaanderen.be”
Afzender/Referte	Unieke referte door MAGDA toegekend aan dit bestand.
Ontvanger/Identificatie	De Uri zoals opgegeven in het vraagbestand
Ontvanger/Referte	De referte zoals opgegeven in het vraagbestand
Afzender/Hoedanigheid	Indien van toepassing: de hoedanigheidscode zoals opgegeven in het vraagbestand

Voorbeeld

<Context>
	<Naam>GeefPersoon</Naam>
	<Versie>02.00.0000</Versie>
	<Bericht>
		<Type>ANTWOORD</Type>
		<Tijdstip>
			<Datum>2014-09-15</Datum>
			<Tijd>01:13:51.831</Tijd>
		</Tijdstip>
		<Afzender>
			<Identificatie>vip.vlaanderen.be</Identificatie>
			<Referte>2ffd784c-7bde-4da4-848e-3a8da25042b8</Referte>
		</Afzender>
		<Ontvanger>
			<Identificatie>***URI***</Identificatie>
			<Referte>257dbfd6-a823-499f-80f7-0a883336fc62</Referte>
			<Hoedanigheid>***HC***</Hoedanigheid>
		</Ontvanger>
	</Bericht>
</Context>

Op deze pagina

1 Algemeen
- 1.1 Service XSD
- 1.2 FTP folder
- 1.3 Bestandsnaam
2 Opbouw vraag bestand
3 Opbouw antwoord bestand

Verbonden pagina’s

MAGDA Gebruikersomgeving

Werking webservice in batch

Informatie:

Algemeen

Service XSD

Informatie:

FTP folder

Bestandsnaam

Opbouw vraag bestand

Opbouw antwoord bestand

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