Document toolboxDocument toolbox


DIGITAAL VLAANDEREN

Werking webservice in batch

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>

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