DIGITAAL VLAANDEREN
Werking webservice in batch
- Paulin Van Biesen
- Pedro Devogelaere (Deactivated)
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 |
|---|---|
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>
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 |
|---|---|
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 | |
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>
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”.
Related content
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