Uitgiftehandboek GMW

Inleiding

Doel en doelgroep uitgiftehandboek

In de basisregistratie ondergrond (BRO) wordt een aantal typen gegevens geregistreerd, de registratieobjecten. Een van de registratieobjecten is de grondwatermonitoringput.

Het uitgiftehandboek richt zich op de partijen die de grondwatermonitoringput van de BRO willen opvragen en beschrijft hoe het proces van gegevensuitgifte globaal verloopt.

Het doel is de afnemers van gegevens, de data-afnemers, in algemeen begrijpelijke bewoordingen inzicht te geven in de stappen die in dit proces worden doorlopen, in de begrippenwereld die wordt gehanteerd, in de vormen van controle en in de berichten die tussen de afnemer en de registerbeheerder worden uitgewisseld.

Samenhang met andere documentatie

Voor ieder registratieobject in de BRO worden de volgende beschrijvende documenten opgesteld:

• een catalogus,
• de handboeken voor inname en uitgifte;
• de koppelvlakbeschrijvingen voor inname en uitgifte.

De catalogus beschrijft de gegevensinhoud van een registratieobject en vormt de basis voor de andere beschrijvende documenten. In de catalogus staan de definities van de gegevens en alle regels waaraan zij moeten voldoen.

Een handboek voor inname of uitgifte beschrijft het proces dat bij inname of uitgifte van gegevens wordt doorlopen, dit document.

De koppelvlakbeschrijvingen zijn geschreven voor softwareontwikkelaars en zijn bedoeld voor de partijen die de webservices gaan gebruiken. Op basis van de twee vorige typen documenten staat hierin beschreven hoe het registratieobject en de processen van inname of uitgifte worden vertaald naar het technische koppelvlak dat is gerealiseerd door middel van webservices. De koppelvlakbeschrijving gaat dus in op de technische kant van de overdracht van gegevens.

Deze documenten hangen samen zoals hieronder afgebeeld.

Leeswijzer

Hoofdstuk 1 geeft het doel en de doelgroep, de samenhang met andere documenten en de versiehistorie van dit uitgiftehandboek.

Hoofdstuk 2 geeft een inleiding op de uitgifte van gegevens uit de basisregistratie ondergrond.

Hoofdstuk 3 gaat in op de berichten die bij het gebruik van de webservice worden uitgewisseld. Het hoofdstuk vertelt welke gegevens een data-afnemer moet meesturen met zijn verzoek en welke gegevens hij terug kan verwachten als antwoord.

Hoofdstuk 4 geeft een specificatie van de berichten die worden uitgewisseld bij gebruik van de webservice inclusief de gegevens die de afnemer krijgt.

Versiehistorie

Contactinformatie

Voor vragen, suggesties of opmerkingen over de inhoud van dit document kunt u contact opnemen met deBRO servicedesk. Bel 088 - 8644 999 of mail naar support@broservicedesk.nl. Verder vind u op basisregistratieondergrond.nl verdere technische inhoudelijke instructie voor het opvragen van gegevens bij de Landelijke voorziening.

Uitgifte

Uitgiftewebservice

De gebruiker die via de webservice gegevens opvraagt krijgt de gegevens onmiddellijk geleverd. Maar om de webservice te kunnen gebruiken moet hij wel over software beschikken die de webservice kan aanroepen en moet hij zich als data-afnemer bij de BRO laten registreren. De eis die daarbij wordt gesteld is dat de organisatie waar hij werkt beschikt over een PKIoverheid services server certificaat. Dat certificaat is een soort digitaal paspoort, het legitimatiebewijs van het softwaresysteem van de gebruiker.

Opvragen van gegevens via de uitgiftewebservice is snel, betrouwbaar en elementair. Dat laatste betekent in de eerste plaats dat er voor ieder type registratieobject een aparte webservice is. Wil men gegevens van meer dan een type opvragen, dan moet men verschillende webservices gebruiken. Verder heeft de gebruiker beperkte keuzevrijheid. Hij kan of alle gegevens van een enkel registratieobject opvragen of een beperkte selectie van gegevens van een aantal registratieobjecten tegelijk. De reden daarachter is dat een webservice alleen in algemene gebruikerswensen voorziet. De eigen software van de data-afnemer moet zo zijn ingericht dat de webservice wordt aangeroepen op een manier die aansluit op de eigen bedrijfsprocessen.

Het proces van uitgifte is bij het gebruik van de webservice strikt geformaliseerd. De webservice verzorgt de communicatie tussen twee softwaresystemen en om te borgen dat de verwerking van een verzoek automatisch kan verlopen zijn er allerlei controles ingebouwd. Een aspect is dat men de gegevens altijd in het IMBRO-XML formaat krijgt.

Communicatie tussen twee systemen

De data-afnemer die voor het opvragen van gegevens van grondwatermonitoringputten gebruik maakt van de uitgiftewebservice, gebruikt via zijn eigen systeem algemene BRO-software die via het internet voor iedereen te vinden is.

De webservice zorgt ervoor dat het systeem van de data-afnemer een verzoek tot verzending van een grondwatermonitoringput aan het BRO-systeem kan aanbieden, zorgt voor de verwerking van het verzoek en geeft het antwoord van de BRO terug aan het systeem van de data-afnemer (Figuur 2). Als alles goed is gegaan bevat het antwoord de opgevraagde gegevens.

Opties bij opvragen via de webservice

De uitgiftewebservice voorziet in elementaire functionaliteit en die dekt drie gebruikscasussen. De eerste is het geval waarin een gebruiker aanvankelijk niet precies weet welke objecten hij wil hebben en daarom op zoek gaat naar de objecten die aan bepaalde kenmerken voldoen.

De tweede casus is het geval waarin de gebruiker weet welke objecten aan zijn kenmerken voldoen en hij alleen de actuele gegevens van een object wil opvragen. Actueel wil zeggen de gegevens met de waarde die op het moment van opvragen geldt. De grondwatermonitoringput is namelijk een registratieobject met een materiële geschiedenis en dat betekent dat de waarde van bepaalde gegevens in de loop van de tijd kan wijzigen.

De derde casus is het geval waarin de gebruiker weet welke objecten aan zijn kenmerken voldoen en hij de historische waarden van de gegevens van een object wil opvragen.

De drie opties zijn vertaald in twee verzoeken:

1. Een verzoek tot verzending van de kengegevens van een aantal grondwatermonitoringputten.

De data-afnemer geeft in zijn verzoek de verzameling kenmerken mee waaraan de grondwatermonitoringputten die hij zoekt moeten voldoen. In antwoord daarop krijgt hij van ieder van de objecten die aan de kenmerken voldoen de gegevens geleverd die het object karakteriseren, met ter identificatie het BRO-ID.

1. Een verzoek tot verzending van de gegevens van een bepaalde grondwatermonitoringput.

De data-afnemer geeft in zijn verzoek het BRO-ID van het grondwatermonitoringput die hij wil hebben mee en specificeert of hij alleen de actuele gegevens of de historische gegevens wil hebben. In antwoord daarop krijgt hij de gevraagde gegevens van de put geleverd.

In de volgende paragrafen wordt de verwerking in meer detail beschreven.

Opvragen van kengegevens

Het opvragen van kengegevens verloopt volgens een vaste opeenvolging van stappen.

Dit is waar het in het kort op neerkomt:

1. De data-afnemer stuurt vanuit zijn systeem een verzoek tot verzending van kengegevens. Daarbij geeft hij de kenmerken mee van de grondwatermonitoringputten waarvan hij gegevens wil krijgen.
2. Het systeem van de BRO voert een toegangscontrole uit.
3. Wanneer toegang tot het systeem van de BRO is verkregen, begint de controle van het verzoek en wordt onder meer vastgesteld of het verzoek inhoudelijk aan de gestelde eisen voldoet.
   • Wanneer de inhoudelijke controle fouten oplevert, wordt het verzoek afgewezen en ontvangt het systeem van de data-afnemer een bericht van afwijzing.
4. Wanneer de inhoudelijke controle geen fouten oplevert en er ook geen technische problemen zijn, verzamelt het systeem van de BRO de kengegevens van de grondwatermonitoringputten die aan de meegegeven kenmerken voldoen.
   • Wanneer de verzameling gegevens te groot is (>2.000), wijst het BRO-systeem het verzoek tot verzending alsnog af en ontvangt het systeem van de data-afnemer een bericht van afwijzing.
   • Wanneer de verzameling onder het gestelde maximum ligt stuurt het BRO-systeem de data-afnemer de opgevraagde gegevens in een bericht van verzending.

Het verzoek van de data-afnemer en het antwoord dat de BRO daarop normaliter geeft worden berichten genoemd. In het geval zich technische problemen voordoen, wordt het antwoord een melding genoemd.

De stappen en de bijbehorende berichten worden in het onderstaande plaatje uitgebeeld.

Opvragen van gegevens

Het opvragen van de gegevens van een grondwatermonitoringput verloopt iets anders dan het opvragen van kengegevens.

Opvragen via de webservice: de berichten

Opvragen van kengegevens

Het opvragen van de kengegevens van een aantal grondwatermonitoringputten verloopt op basis van één of meer kenmerken.

Verzoek tot verzending

Het belangrijkste onderdeel van het verzoek tot verzending van kengegevens is de kenmerkenverzameling, dat is het geheel van kenmerken waaraan de grondwatermonitoringput die de afnemer wil krijgen moet voldoen. Door het meegeven van kenmerken kan de data-afnemer de zoekvraag preciseren naar plaats, tijd en aard van de constructie.

De kenmerken die de data-afnemer kan kiezen, worden in hoofdstuk 4 gespecificeerd. Het is een keuze uit de gegevens die in de catalogus voor de grondwatermonitoringput zijn beschreven, met daarbij aangegeven hoe de waarde moet worden gespecificeerd.

De data-afnemer moet als kenmerk in ieder geval opgeven in welk gebied de locatie van de grondwatermonitoringput moet liggen. Dat kenmerk kan hij combineren met een of meer andere kenmerken.

Naast deze kenmerken moet de data-afnemer een verzoekkenmerk meegeven. Dat gegeven kan worden gebruikt in de communicatie met de BRO Servicedesk, bijvoorbeeld als er iets mis is gegaan en de data-afnemer wil over het probleem contact zoeken met de BRO Servicedesk.

Bericht van afwijzing

In de verwerking van het verzoek zijn allerlei controles ingebouwd. Als er in technische zin iets mis gaat, krijgt de data-afnemer een melding. Een bericht van afwijzing krijgt hij als antwoord, wanneer bij de controles blijkt dat zich een probleem voordoet dat bij het invoeren van gegevens moet worden opgelost.

Figuur 5: Twee controles kunnen leiden tot een bericht van afwijzing.

Het bericht van afwijzing bevat het tijdstip van afwijzing en het verzoekkenmerk van de data-afnemer, maar het belangrijkste onderdeel is de reden afwijzing. De reden waarom het verzoek is afgewezen hangt af van de aard van het probleem. Het probleem kan zijn dat er een fout zit in de gegevens die de data-afnemer heeft meegegeven, maar het kan ook zijn dat bij het verzamelen van gegevens blijkt dat het maximum aantal registratieobjecten wordt overschreden.

Fouten in de gegevens die de data-afnemer heeft meegegeven worden in het bericht zo omschreven dat de afnemer direct kan zien waar de fout zit en wat de fout inhoudt.

Het bericht van afwijzing dat gestuurd wordt na de tweede controle heeft een eenvoudige boodschap. Het aantal objecten waarvan kengegevens worden geleverd is beperkt tot 2.000. De foutmelding geeft in dit geval alleen aan dat het maximum is overschreden.

Bericht van verzending

Het belangrijkste onderdeel van het bericht van verzending zijn de uitgiftedocumenten. Ieder uitgiftedocument bevat de kengegevens van een grondwatermonitoringput die de gewenste kenmerken heeft. Het bericht bevat verder het tijdstip van uitgifte, het verzoekkenmerk van de data-afnemer en de vermelding van het aantal uitgiftedocumenten. Er worden maximaal 2.000uitgiftedocumenten verzonden.

De lijst met kengegevens die standaard worden uitgegeven wordt gespecificeerd in hoofdstuk 4.

Er is één uitzondering op de standaardlijst en dat is wanneer een registratieobject door de registerbeheerder uit registratie is genomen. Dat geval doet zich bijvoorbeeld voor wanneer een object ten onrechte is opgenomen in de registratie en de registerbeheerder, na onderzoek en overleg met de bronhouder, van die laatste het akkoord heeft gekregen het object uit registratie te nemen. In dat uitzonderlijke geval ontvangt de data-afnemer een bijzonder type uitgiftedocument dat enkel de volgende gegevens over het betreffende registratieobject bevat:

Tot slot kan het voorkomen dat er geen enkel registratieobject bestaat dat aan de kenmerken voldoet die zijn meegegeven. Dan ontvangt de data-afnemer wel een bericht van verzending, maar worden er geen uitgiftedocumenten meegeleverd.

Opvragen van gegevens

Het opvragen van de gegevens van een grondwatermonitoringput verloopt op basis van het BRO-ID.

Verzoek tot verzending

Het verzoek tot verzending van de gegevens van een grondwatermonitoringput bestaat uit drie gegevens. Het verzoekkenmerk, het BRO-ID van de grondwatermonitoringput dat de data-afnemer wil krijgen en een aanduiding van de te leveren gegevens. Met het laatste geeft de data-afnemer aan of hij de actuele gegevens of de historische gegevens van een grondwatermonitoringput wil ontvangen.

Bericht van afwijzing

Een bericht van afwijzing wordt bij dit type verzoek alleen gestuurd als de BRO een fout in het verzoek zelf heeft geconstateerd, dus wanneer er bij het invoeren van het verzoekkenmerk of het BRO-ID iets mis is gegaan. De controle is eenvoudig: de drie gegevens moeten aan de specificaties (zie hoofdstuk 4) voldoen. Ook wanneer de data-afnemer per ongeluk een BRO-ID heeft opgegeven dat niet bestaat, stuurt de BRO een bericht van afwijzing als antwoord.

Bericht van verzending

Het bericht van verzending bevat maar een uitgiftedocument en dat bevat de gewenste gegevens van de opgevraagde grondwatermonitoringput. Verder bevat het bericht de verwijzing naar het verzoek tot verzending en het tijdstip waarop de gegevens zijn verzonden.

Welke gegevens er precies in het uitgiftedocument zitten hangt niet alleen af van wat de data-afnemer heeft opgevraagd. Het wordt ook bepaald door de vraag of de data-afnemer tevens de bronhouder of de data-leverancier van de betreffende grondwatermonitoringput is. Die twee partijen krijgen alle gegevens van het registratieobject geleverd. Dat geldt zelfs in het uitzonderlijke geval dat het registratieobject door de registerbeheerder uit registratie is genomen.

De andere data-afnemers krijgen alle gegevens op drie na. De drie gegevens die ze niet geleverd krijgen zijn:

In het uitzonderlijke geval dat het registratieobject uit registratie is genomen, krijgen de andere data-afnemers, zijnde niet bronhouder of de data-leverancier, een ander type uitgiftedocument dat alleen de volgende gegevens bevat:

Meldingen

Een melding is het antwoord dat de BRO stuurt wanneer er op technisch vlak iets mis is gegaan. Meldingen zijn in eerste instantie bedoeld voor programmeurs. Om die reden worden de meldingen uitgebreid behandeld in de koppelvlakbeschrijving; hier wordt alleen achtergrondinformatie gegeven.

De oorzaak van een technisch probleem kan variëren en er worden drie categorieën meldingen onderscheiden:

• melding van een probleem bij de toegangscontrole,
• melding van een probleem in de software van de data-afnemer,
• melding van een systeemfout.

Toegangscontrole houdt in dat het systeem van de BRO controleert of de data-afnemer daadwerkelijk is wie hij beweert te zijn en of hij het recht heeft gebruik te maken van de uitgiftewebservice. Het optreden van een probleem bij de toegangscontrole is uitzonderlijk en het zal zich eigenlijk alleen voordoen wanneer een data-afnemer voor het eerst gebruik wil maken van de webservice.

Problemen in de software van de data-afnemer kunnen vaker optreden, maar ook deze zullen zich in eerste instantie met name openbaren in de fase waarin de data-afnemer bezig is zijn software geschikt te maken voor aansluiting op de BRO.

Systeemfouten doen zich voor wanneer er problemen zijn met de software van de BRO of wanneer zich onvoorziene omstandigheden voordoen, bijvoorbeeld wanneer de stroomtoevoer hapert.

Specificatie van de berichten bij gebruik van de webservice

Inleiding

In dit hoofdstuk worden de gegevensinhoud beschreven van de berichten die bij uitgifte worden uitgewisseld tussen het systeem van de data-afnemer en het BRO-systeem. De systematiek van de beschrijving is dezelfde als in de catalogus.

Eerst worden de berichten beschreven op basis van een model dat de vorm heeft van een UML-diagram. Na de berichten worden de domeinen behandeld die specifiek zijn voor de berichten. Aan het eind van het hoofdstuk worden de UML-modellen van de verschillende typen uitgiftedocumenten gegeven.

Het handboek is een aanvulling op de catalogus en om die reden wordt een gegeven hier alleen gedefinieerd wanneer het niet in de catalogus is opgenomen of wanneer er bijzondere regels gelden. Wanneer alleen de kardinaliteit van een gegeven afwijkt van die in de catalogus, is dat geen reden geweest het hier op te nemen.

Berichten

Verzoek tot verzending kengegevens

Verzoek tot verzending gegevens

Bericht van afwijzing

Bericht van verzending kengegevens

Bericht van verzending gegevens

Specifieke domeinen voor uitgifte

Rechthoek

Het domein van het type rechthoek wordt gebruikt voor een gebied op aarde dat als een rechthoek wordt voorgesteld. De rechthoek wordt gedefinieerd door twee punten die op het aardoppervlak liggen. Dat zijn in deze volgorde het punt dat de zuidwesthoek, resp. de noordoosthoek vertegenwoordigt. Ieder van de punten wordt uitgedrukt in het domein Coördinatenpaar (zie de catalogus) met als referentiestelsel ETRS89 (ongeprojecteerd).

Het coördinatenpaar voor ETRS89 (φ,λ) is als volgt gedefinieerd:
Getalswaarde 2.9
Eenheid ° (graden, decimaal) Bereik φ tussen 50.6 en 56
Bereik λ tussen 2.4 en 7.4

Cirkel

Het domein van het type cirkel wordt gebruikt voor een gebied op aarde dat als een cirkel wordt voorgesteld en wordt gedefinieerd door een middelpunt en een straal. Het middelpunt is een punt op het aardoppervlak en wordt uitgedrukt in het domein Coördinatenpaar (zie de catalogus) met als referentiestelsel ETRS89 (ongeprojecteerd).

De straal is de geodetische afstand van het middelpunt tot een punt op de cirkel en wordt uitgedrukt als een getalswaarde (zie de catalogus).

Getalswaardeinterval

Een domein van het type getalswaardeinterval omvat een bepaald deel van een bepaalde verzameling getallen. Binnen de BRO zijn drie verzamelingen getallen van belang de natuurlijke, de gehele, en de rationale getallen. Het getalswaardeinterval kent een onder- en een bovengrens en ook de beide grensgetallen maken deel uit van de verzameling.

Een domein van het type getalswaardeinterval wordt in de BRO gebruikt voor gegevens die gemeten, berekend of anderszins bepaald zijn. Bij de getalswaarde hoort daarom een eenheid. De BRO gebruikt voor de eenheden de codes uit het UCUM (Unified Code for Units of Measure)-systeem. In bijzondere gevallen is de eenheid dimensieloos.

Wanneer een attribuut een domein van het type getalswaardinterval heeft worden de minimale waarde voor de ondergrens (minimum) en de maximale waarde voor de bovengrens van het interval (maximum) opgegeven, wordt gespecificeerd of het gehele of rationale getallen betreft, en wordt de eenheid waarop de getalswaarden betrekking hebben opgegeven.

Datuminterval

Het datuminterval is een van de drie domeinen die voor gegevens die over een interval in de tijd, een periode, gaan. Het domein wordt gebruikt voor een periode die tot op de dag nauwkeurig begrensd is. Het domein datuminterval bestaat uit een begindatum en een einddatum, beide van het domeintype Datum (JJJJ-MM-DD, zie de catalogus).

De basisregistratie ondergrond hanteert de volgende praktische regels:

• Het begin ligt voor het einde of valt daarmee samen.
• Het waardebereik is inclusief en omvat de begin- en de einddatum
• Een aanvullende regel is nodig om aan te geven wanneer een temporeel gegeven uit het domein OnvolledigeDatum in het interval ligt, en wanneer niet. Om die regel te formuleren wordt een OnvolledigeDatum beschouwd als een interval.
  • Een OnvolledigeDatum valt alleen binnen het bereik van een datuminterval wanneer het interval in zijn geheel binnen het datuminterval valt (of daarmee samenvalt).
  • Gegevens met de waarde onbekend worden niet uitgegeven o.b.v. een datuminterval.

Kenmerkfout

Een waarde in de lijst is een zin met een bepaalde opbouw en met zowel vaste als variabele bestanddelen. De variabele bestanddelen gegeven aan waar de fout in de kenmerkenverzameling zit en eventueel waarom het een fout is.

Een eerste variabel element is <gegeven>. Dat geeft aan welk gegeven onjuist is. Wanneer het gaat om een onjuiste waarde wordt met het gegeven ook de waarde van het gegeven opgenomen (<gegeven = waarde>).

Een tweede variabel element is <referentiegegeven> en dat wordt opgenomen wanneer er een tweede gegeven is dat bepaalt dat het <gegeven> fout is. Zo nodig wordt ook hier de waarde meegegeven (<referentiegegeven = waarde>).

Een derde variabel element is <referentiewaarde> en dat wordt opgenomen wanneer een waardebereik bepaalt dat het <gegeven> fout is.

RedenAfwijzing

Net als bij het domein Kenmerkfout is een waarde een zin met een bepaalde opbouw die vaste en variabele bestanddelen heeft.

TeLeverenGegevens

Uitgiftedocumenttype

Uitgiftedocumenten

BRO-DO

GMW-C

GMW-PO

Zie figuur 6.

GMW-PO-DP

Het verschil met GMW-PO is dat het uitgiftedocument ook de gegevens object-ID bronhouder, dataleverancier en onderhoudende instantie bevat.

GMW-PPO

Zie figuur 7.

GMW-PPO-DP

Het verschil met GMW-PPO is dat het uitgiftedocument ook de gegevens object-ID bronhouder, dataleverancier en onderhoudende instantie bevat.