Elke MAGDA 2.0 webservice is niet enkel als een SOAP te benaderen maar o=
ok door middel van een bestand. Dit bestand bevat =C3=A9=C3=A9n tot meerder=
e vragen die dan achterliggend door de webservice verwerkt zullen =
worden. Het resultaat van de verwerking verkrijgt men eveneens als bestand =
aangeleverd.
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 d=
e vraag en een Reponse XSD voor het antwoord.
FTP folder
Wenst de afnemer de webservices via batch te bevragen, dan verkrijgt dez=
e tijdens het aansluitingsproces een FTP-folder. De afnemer toepassing plaa=
tst de vraagbestanden in de To_Vip folder. MAGDA zal dat bestand binnen een=
bepaalde tijd detecteren (op basis van een voorgedefinieerd benamingspatro=
on), oppikken en verwerken. Het bestand zal dan eerst worden gekopieerd naa=
r de cache/to_vip folder en daarna worden doorgegeven naar de MAGDA verwerk=
ingsomgeving. Na verwerking door MAGDA komt het antwoordbestand in de From_=
Vip folder terecht.
Voor meer informatie betreffende de MAGDA FTP omgeving en geldende richt=
lijnen 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 webs=
ervice uitgevoerd moet worden.
Na de prefix moet de bestandsnaam aangevuld met datum en tijdstip (tot o=
p miliseconden). Het is toegelaten om in de bestandsnaam ook een intern vol=
gnummer of andere identificaties toe te voegen.
Belangrijk is wel dat elk aangeboden bestand een unieke bestandsnaam moe=
t hebben. De bestanden mogen ook in een .zip aangeleverd worden.
Voorbeeld prefix: Persoon.GeefPersoon-0200_201409051815=
0_0001.xml
Opbouw vraag bestand=
De vraag XSD binnen de Service folder is op dezelfde manier opgebouwd al=
s deze voor de Webservice maar laat wel meerdere Vraag-elementen toe. Hierd=
oor is het mogelijk om meerdere vragen te bundelen in =C3=A9=C3=A9n bestand=
en is het niet nodig om voor elke vraag een bestand aan te maken.
In de Vraag XSD identificeren we twee delen:
Voorbeeld: de Service vraag XSD van de GeefPersoo=
n service
Merk in bovenstaande afbeelding op dat het Vraagelement een kardinalitei=
t heeft van 1 tot =E2=88=9E en niet 1..1 zoals bij de webservice XSD.
Context
Binnen het Context-segement worden de afnemerparameters opgenomen ter id=
entificatie. Onderstaande tabel duidt aan welke gegevens binnen Context ing=
evuld moeten worden en met welke waardes.
Element |
Inhoud |
Naam |
Dienstnaam, exclusief het versienummer. Bijvoorbeeld =E2=80=9CGeefPersoo=
n=E2=80=9D. |
Versie |
Versie van de dienst in formaat xx.xx.xxxx, bijvoorbeeld 02.00.0000 =
; |
Type |
Steeds =E2=80=9CVRAAG=E2=80=9D |
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 MAGD=
A platform |
Afzender/Naam |
Naam van de (overheids)dienst. |
Afzender/Referte |
Unieke referte, de referte moet uniek zijn over al de door de afn=
emer aangeleverde bestanden. De vragen gesteld door de afnemer kunnen n=
amelijk verspreid zijn over meerdere bestanden. Dit is geprefereerd ee=
n UUID van 36 lang., voorbeeld d32a4a2f-6353-47fb-9563-594fbed1ebd4.
|
Afzender/Hoedanigheid |
Indien van toepassing: de hoedanigheidscode die men verkregen heeft tijd=
ens het toelatingsproces tot het MAGDA platform |
Ontvanger/Identificatie |
Steeds =E2=80=9Cvip.vlaanderen.be=E2=80=9D |
Voorbeeld
<Cont=
ext>
=09<Naam>GeefPersoon</Naam>
=09<Versie>02.00.0000</Versie>
=09<Bericht>
=09=09<Type>VRAAG</Type>
=09=09<Tijdstip>
=09=09=09<Datum>2014-07-09</Datum>
=09=09=09<Tijd>03:07:24.000</Tijd>
=09=09</Tijdstip>
=09=09<Afzender>
=09=09=09<Identificatie>***URI***</Identificatie>
=09=09=09<Naam>DHO</Naam>
=09=09=09<Referte>550e8400-e29b-41d4-a716-446655440000</Referte>=
;
=09=09=09<Hoedanigheid>***HC***</Hoedanigheid>
=09=09</Afzender>
=09=09<Ontvanger>
=09=09=09<Identificatie>vip.vlaanderen.be</Identificatie>
=09=09</Ontvanger>
=09</Bericht>
</Context>
Vragen/Vraag
Binnen het Vraag-element bevindt zich de uiteindelijke vraag. Het is mog=
elijk om meerdere Vraag-elementen op te geven, in feite oneindig. Al wordt =
aangeraden om het aantal Vraag-elementen beperkt te houden, bvb tot 1000. K=
leinere bestanden zijn namelijk sneller verwerkt.
Binnen het Vraag-element bevinden zich
=
Voorbeeld
<Vrag=
en>
=09<Vraag>
=09=09<Referte>219cd2a7-41ad-4de4-944d-5e5a1c7d1ba3</Referte>
=09=09<Inhoud>
=09=09=09<Criteria>
=09=09=09=09<INSZ>11122255587</INSZ>
=09=09=09</Criteria>
=09=09=09<Bron>RR</Bron>
=09=09=09<Taal>nl</Taal>
=09=09</Inhoud>
=09</Vraag>
=09<Vraag>
=09=09<Referte>cc70bfa0-1de5-4b13-9ba1-bd3553adfffd</Referte>
=09=09<Inhoud>
=09=09=09<Criteria>
=09=09=09=09<INSZ>11223366554</INSZ>
=09=09=09</Criteria>
=09=09=09<Bron>SOA</Bron>
=09=09=09<Taal>nl</Taal>
=09=09</Inhoud>
=09</Vraag>
</Vragen>
Referte
De Referte binnen het Vraag-element moet uniek zijn voor al de Vraag-ele=
menten, dus niet enkel in dit bestand maar eventueel ook in andere door de =
afnemer aangeboden bestanden of webservice oproepen. Idealiter wordt een da=
tum/tijdstip gebruikt, al wordt een UUID van 36 geprefereerd verkozen. =
;
Inhoud
De Inhoud is afhankelijk van de webservice die aangeroepen wordt. Hiervo=
or wordt verwezen naar de gebruikershandleiding de dienst specifieke handle=
idingen, te vinden op Handleidingen dienstenaanbod.
Opbouw antwoord b=
estand
Eens het vraagbestand verwerkt is verkrijgt de afnemer in de From_vip he=
t antwoordbestand. Dit bestand bevat op zich weer een Context alsook de Ant=
woorden. Het bestand kan ook Uitzonderingen bevatten. De afnemer verkrijgt =
geen melding als een bestand beschikbaar is! De afnemer moet zelf op regelm=
atige tijdstippen controleren op de aanwezigheid van een bestand.
Voorbeeld: de antwoord XSD van de GeefPersoon service.<=
/p>
Context
De Context in het antwoord is in feite een spiegelbeeld van de Context i=
n de vraag.
Element |
Inhoud |
Naam |
Dienstnaam |
Versie |
Versie van de dienst |
Type |
Steeds =E2=80=9CANTWOORD=E2=80=9D |
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 <=
/td>
|
Afzender/Identificatie |
=E2=80=9Cvip.vlaanderen.be=E2=80=9D |
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 vraag=
bestand |
Voorbeeld
<Cont=
ext>
=09<Naam>GeefPersoon</Naam>
=09<Versie>02.00.0000</Versie>
=09<Bericht>
=09=09<Type>ANTWOORD</Type>
=09=09<Tijdstip>
=09=09=09<Datum>2014-09-15</Datum>
=09=09=09<Tijd>01:13:51.831</Tijd>
=09=09</Tijdstip>
=09=09<Afzender>
=09=09=09<Identificatie>vip.vlaanderen.be</Identificatie>
=09=09=09<Referte>2ffd784c-7bde-4da4-848e-3a8da25042b8</Referte>=
;
=09=09</Afzender>
=09=09<Ontvanger>
=09=09=09<Identificatie>***URI***</Identificatie>
=09=09=09<Referte>257dbfd6-a823-499f-80f7-0a883336fc62</Referte>=
;
=09=09=09<Hoedanigheid>***HC***</Hoedanigheid>
=09=09</Ontvanger>
=09</Bericht>
</Context>
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 antwoordbesta=
nd aan elkaar te koppelen.
Voor het Inhoud-element van het Antwoord wordt verwezen naar de gebruike=
rshandleiding van de webservice: Handleidingen dienstenaanbod=
a>.
De Referte binnen het Antwoord is dit zoals opgegeven in de Vraag. Op di=
e manier kan een specifiek Antwoord aan een specifieke Vraag geli=
nkt worden. Het aantal antwoorden in de vraag komt steeds overeen met =
het aantal vragen dat gesteld is geweest in het vraagbestand.
Voorbeeld
<Antw=
oorden>
=09<Antwoord>
=09=09<Referte>28870fac-9922-48e6-86a7-1fb736dbf16a</Referte>
=09=09<Inhoud>
=09=09=09<Resultaat Beschrijving=3D"Wel geslaagd">1</Resultaat>
=09=09=09<Inschrijving>
=09=09=09=09<INSZ>45678912351</INSZ>
=09=09=09</Inschrijving>
=09=09</Inhoud>
=09</Antwoord>
=09<Antwoord>
=09=09<Referte>348df3ee-192d-4e4a-8bf1-5c1de175ef68</Referte>
=09=09<Inhoud>
=09=09=09<Resultaat Beschrijving=3D"Wel geslaagd">1</Resultaat>
=09=09=09<Inschrijving>
=09=09=09=09<INSZ>48965741256</INSZ>
=09=09=09</Inschrijving>
=09=09</Inhoud>
=09</Antwoord>
</Antwoorden>
Voorbeeld met uitzondering
<zpnd=
:ZoekPersoonOpNaamResponse xmlns:zpnd=3D"http://service.zoekpersoonopnaamdi=
enst.vip.vlaanderen.be">
=09<Repliek>
=09=09<Context>
=09=09=09<Naam>ZoekPersoonOpNaam</Naam>
=09=09=09<Versie>01.01.0000</Versie>
=09=09=09<Bericht>
=09=09=09=09<Type>ANTWOORD</Type>
=09=09=09=09<Tijdstip>
=09=09=09=09=09<Datum>2013-12-17</Datum>
=09=09=09=09=09<Tijd>13:07:48.182</Tijd>
=09=09=09=09</Tijdstip>
=09=09=09=09<Afzender>
=09=09=09=09=09<Identificatie>vip.vlaanderen.be</Identificatie>
=09=09=09=09=09<Naam>VIP</Naam>
=09=09=09=09=09<Referte>49fddd60-5ecb-45cf-8eac-78001578188c</Refe=
rte>
=09=09=09=09</Afzender>
=09=09=09=09<Ontvanger>
=09=09=09=09=09<Identificatie>*******************</Identificatie&g=
t;
=09=09=09=09=09<Naam>Onderwijs-Lerende Mens</Naam>
=09=09=09=09=09<Referte>868774f9-cc33-4bf6-acd1-a0282e42d062</Refe=
rte>
=09=09=09=09=09<Hoedanigheid>**************</Hoedanigheid>
=09=09=09=09</Ontvanger>
=09=09=09</Bericht>
=09=09</Context>
=09=09<Antwoorden>
=09=09=09<Antwoord>
=09=09=09=09<Referte>4ea7a924-72ed-4c02-8a18-3b1bbfdc46bb</Referte=
>
=09=09=09=09<Inhoud>
=09=09=09=09=09<Personen>
=09=09=09=09=09=09<Persoon>
=09=09=09=09=09=09=09<INSZ>12345678910</INSZ>
=09=09=09=09=09=09=09<AuthentiekeBronCode Beschrijving=3D"KSZ">02<=
/AuthentiekeBronCode>
=09=09=09=09=09=09=09<Naam DatumModificatie=3D"2013-11-22">
=09=09=09=09=09=09=09=09<Achternaam>achternaam</Achternaam>
=09=09=09=09=09=09=09=09<Voornaam>voornaam</Voornaam>
=09=09=09=09=09=09=09=09<VoornaamVolledigVlag>0</VoornaamVolledigV=
lag>
=09=09=09=09=09=09=09</Naam>
=09=09=09=09=09=09=09<Geslacht Beschrijving=3D"Vrouwelijk" DatumModifica=
tie=3D"2013-11-22">2</Geslacht>
=09=09=09=09=09=09=09<Geboorte DatumModificatie=3D"2002-07-13">
=09=09=09=09=09=09=09=09<Datum>2002-07-13</Datum>
=09=09=09=09=09=09=09</Geboorte>
=09=09=09=09=09=09=09<Adres>
=09=09=09=09=09=09=09=09<AuthentiekeBronCode Beschrijving=3D"KSZ" DatumM=
odificatie=3D"2013-11-22">02</AuthentiekeBronCode>
=09=09=09=09=09=09=09=09<Straat>
=09=09=09=09=09=09=09=09=09<NISCode>1547</NISCode>
=09=09=09=09=09=09=09=09=09<Naam>STRAAT</Naam>
=09=09=09=09=09=09=09=09</Straat>
=09=09=09=09=09=09=09=09<HuisNummer>6</HuisNummer>
=09=09=09=09=09=09=09=09<Gemeente>
=09=09=09=09=09=09=09=09=09<NISCode>34022</NISCode>
=09=09=09=09=09=09=09=09=09<PostCode>8500</PostCode>
=09=09=09=09=09=09=09=09=09<Naam>KORTRIJK</Naam>
=09=09=09=09=09=09=09=09</Gemeente>
=09=09=09=09=09=09=09=09<Land>
=09=09=09=09=09=09=09=09=09<ISOCode>BEL</ISOCode>
=09=09=09=09=09=09=09=09=09<NISCode>150</NISCode>
=09=09=09=09=09=09=09=09=09<Naam>Belgi=C3=AB</Naam>
=09=09=09=09=09=09=09=09</Land>
=09=09=09=09=09=09=09</Adres>
=09=09=09=09=09=09=09<Nationaliteit DatumModificatie=3D"2013-11-22">
=09=09=09=09=09=09=09=09<ISOCode>NLD</ISOCode>
=09=09=09=09=09=09=09=09<NISCode>129</NISCode>
=09=09=09=09=09=09=09</Nationaliteit>
=09=09=09=09=09=09</Persoon>
=09=09=09=09=09</Personen>
=09=09=09=09</Inhoud>
=09=09=09</Antwoord>
=09=09=09<Antwoord>
=09=09=09=09<Referte>d977dd84-e01d-4c1e-b409-8cfa8dc65a98</Referte=
>
=09=09=09=09<Uitzonderingen>
=09=09=09=09=09<Uitzondering>
=09=09=09=09=09=09<Identificatie>30001</Identificatie>
=09=09=09=09=09=09<Type>FOUT</Type>
=09=09=09=09=09=09<Tijdstip>
=09=09=09=09=09=09=09<Datum>2013-12-17</Datum>
=09=09=09=09=09=09=09<Tijd>13:07:50.483</Tijd>
=09=09=09=09=09=09</Tijdstip>
=09=09=09=09=09=09<Diagnose>Geen gegevens gevonden voor deze vraag<=
;/Diagnose>
=09=09=09=09=09</Uitzondering>
=09=09=09=09</Uitzonderingen>
=09=09=09</Antwoord>
=09=09</Antwoorden>
=09</Repliek>
</zpnd:ZoekPersoonOpNaamResponse>