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.

Info

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.

Info

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

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.

Expand

title	Context

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

Code Block

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

Expand

title	Vragen/Vraag

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

Code Block

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

Expand

title	Referte

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.

Expand

title	Inhoud

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.

Expand

title	Context

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

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

Code Block

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

Expand

title	Antwoorden/Antwoord

De bestandsnaam van het antwoordbestand is identiek aan de bestandsnaam van de vraag. Op deze manier is het eenvoudig om een vraag-en antwoordbestand aan elkaar te koppelen.

Voor het Inhoud-element van het Antwoord wordt verwezen naar de gebruikershandleiding van de webservice: Handleidingen dienstenaanbod.

De Referte binnen het Antwoord is dit zoals opgegeven in de Vraag. Op die manier kan een specifiek Antwoord aan een specifieke Vraag gelinkt worden. Het aantal antwoorden in de vraag komt steeds overeen met het aantal vragen dat gesteld is geweest in het vraagbestand.

Voorbeeld

Code Block

<Antwoorden>
	<Antwoord>
		<Referte>28870fac-9922-48e6-86a7-1fb736dbf16a</Referte>
		<Inhoud>
			<Resultaat Beschrijving="Wel geslaagd">1</Resultaat>
			<Inschrijving>
				<INSZ>45678912351</INSZ>
			</Inschrijving>
		</Inhoud>
	</Antwoord>
	<Antwoord>
		<Referte>348df3ee-192d-4e4a-8bf1-5c1de175ef68</Referte>
		<Inhoud>
			<Resultaat Beschrijving="Wel geslaagd">1</Resultaat>
			<Inschrijving>
				<INSZ>48965741256</INSZ>
			</Inschrijving>
		</Inhoud>
	</Antwoord>
</Antwoorden>

Info

Informatie:

Een antwoordbestand kan zowel gegevens bevatten alsook uitzonderingen. Bijvoorbeeld voor vraag 1 werd een persoon gevonden, voor vraag 2 in datzelfde bestand werden er geen persoonsgegevens gevonden. Antwoord 1 in het antwoordbestand bevat dan de persoonsgegevens, antwoord 2 in het bestand de uitzondering “geen gegevens gevonden”.

Expand

title	Voorbeeld met uitzondering

Code Block

<zpnd:ZoekPersoonOpNaamResponse xmlns:zpnd="http://service.zoekpersoonopnaamdienst.vip.vlaanderen.be">
	<Repliek>
		<Context>
			<Naam>ZoekPersoonOpNaam</Naam>
			<Versie>01.01.0000</Versie>
			<Bericht>
				<Type>ANTWOORD</Type>
				<Tijdstip>
					<Datum>2013-12-17</Datum>
					<Tijd>13:07:48.182</Tijd>
				</Tijdstip>
				<Afzender>
					<Identificatie>vip.vlaanderen.be</Identificatie>
					<Naam>VIP</Naam>
					<Referte>49fddd60-5ecb-45cf-8eac-78001578188c</Referte>
				</Afzender>
				<Ontvanger>
					<Identificatie>*******************</Identificatie>
					<Naam>Onderwijs-Lerende Mens</Naam>
					<Referte>868774f9-cc33-4bf6-acd1-a0282e42d062</Referte>
					<Hoedanigheid>**************</Hoedanigheid>
				</Ontvanger>
			</Bericht>
		</Context>
		<Antwoorden>
			<Antwoord>
				<Referte>4ea7a924-72ed-4c02-8a18-3b1bbfdc46bb</Referte>
				<Inhoud>
					<Personen>
						<Persoon>
							<INSZ>12345678910</INSZ>
							<AuthentiekeBronCode Beschrijving="KSZ">02</AuthentiekeBronCode>
							<Naam DatumModificatie="2013-11-22">
								<Achternaam>achternaam</Achternaam>
								<Voornaam>voornaam</Voornaam>
								<VoornaamVolledigVlag>0</VoornaamVolledigVlag>
							</Naam>
							<Geslacht Beschrijving="Vrouwelijk" DatumModificatie="2013-11-22">2</Geslacht>
							<Geboorte DatumModificatie="2002-07-13">
								<Datum>2002-07-13</Datum>
							</Geboorte>
							<Adres>
								<AuthentiekeBronCode Beschrijving="KSZ" DatumModificatie="2013-11-22">02</AuthentiekeBronCode>
								<Straat>
									<NISCode>1547</NISCode>
									<Naam>STRAAT</Naam>
								</Straat>
								<HuisNummer>6</HuisNummer>
								<Gemeente>
									<NISCode>34022</NISCode>
									<PostCode>8500</PostCode>
									<Naam>KORTRIJK</Naam>
								</Gemeente>
								<Land>
									<ISOCode>BEL</ISOCode>
									<NISCode>150</NISCode>
									<Naam>België</Naam>
								</Land>
							</Adres>
							<Nationaliteit DatumModificatie="2013-11-22">
								<ISOCode>NLD</ISOCode>
								<NISCode>129</NISCode>
							</Nationaliteit>
						</Persoon>
					</Personen>
				</Inhoud>
			</Antwoord>
			<Antwoord>
				<Referte>d977dd84-e01d-4c1e-b409-8cfa8dc65a98</Referte>
				<Uitzonderingen>
					<Uitzondering>
						<Identificatie>30001</Identificatie>
						<Type>FOUT</Type>
						<Tijdstip>
							<Datum>2013-12-17</Datum>
							<Tijd>13:07:50.483</Tijd>
						</Tijdstip>
						<Diagnose>Geen gegevens gevonden voor deze vraag</Diagnose>
					</Uitzondering>
				</Uitzonderingen>
			</Antwoord>
		</Antwoorden>
	</Repliek>
</zpnd:ZoekPersoonOpNaamResponse>

Op deze pagina

Table of Contents

minLevel	1
maxLevel	2

Verbonden pagina’s

Child pages (Children Display)

depth	2
page	Bestandsuitwisseling (Publicaties/batchverwerking)

Info
Met vragen kunt u steeds terecht bij de MAGDA Service Desk.

Versions Compared

Old Version 8

New Version 9

Key

Informatie:

Algemeen

Service XSD

Informatie:

FTP folder

Bestandsnaam

Opbouw vraag bestand

Opbouw antwoord bestand

Informatie:

Page Comparison

Versions Compared

Old Version 8

New Version 9

Key

Informatie:

Algemeen

Service XSD

Informatie:

FTP folder

Bestandsnaam

Opbouw vraag bestand

Opbouw antwoord bestand

Informatie: