Basisregistratie ondergrond (BRO) Uitgiftehandboek

Transcriptie

1 Basisregistratie ondergrond (BRO) Uitgiftehandboek Grondwatermonitoringput Datum augustus 2015 Versie 0.6

2

3 Colofon Bestuurskern Dir. Ruimtelijke Ontwikkeling Plesmanweg 1-6 Den Haag Contactpersoon M.R.H.E. Peersmann (Martin) Programmabureau BRO Directoraat-Generaal Ruimte en Water Versie 0.6 Auteur TNO Geologische Dienst Nederland Pagina 3 van 19

4 Inhoudsopgave 1 Inleiding Doel en doelgroep uitgiftehandboek Samenhang met andere documentatie Leeswijzer Versiehistorie Contactinformatie Uitgifte van gegevens Twee manieren van uitgifte DINOloket of de uitgiftewebservice Uitgifte via de webservice Opvragen van grondwatermonitoringputten via de webservice Het formuleren van een verzoek Een verzoek tot levering van de actuele gegevens van een grondwatermonitoringput De berichten Opvragen van grondwatermonitoringputten via het DINOloket Specificatie van de berichtgegevens bij uitgifte via de webservice Inleiding Attributen en entiteiten Pagina 4 van 19

5 1 Inleiding 1.1 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 grondwatermonitoringputten 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. 1.2 Samenhang met andere documentatie Voor ieder registratieobject in de BRO worden de volgende beschrijvende documenten opgesteld: een catalogus, handboeken voor inname en uitgifte; koppelvlakbeschrijvingen voor inname en uitgifte. In de catalogus staan de definities van alle entiteiten en attributen van het registratieobject beschreven. Tevens zijn hierin een beschrijving van de kardinaliteit (het aantal keer dat de entiteit of het attribuut voorkomt), regels voor het gebruik en de waardes die toegestaan zijn voor de attributen te vinden. Tot slot wordt de samenhang tussen de entiteiten beschreven. De catalogus beschrijft dus de inhoud van de BRO en vormt de basis voor de andere beschrijvende documenten. Een handboek voor inname of uitgifte beschrijft het proces dat bij inname of uitgifte van gegevens wordt doorlopen. Alle registratieobjecten kunnen aangeboden worden via webservices, bepaalde registratieobjecten kunnen ook aangeboden worden via het innameloket. Bij uitgifte is het anders en kan de afnemer voor alle objecten kiezen tussen webservices of DINOloket. In een handboek worden ook de gegevens gedefinieerd die betrekking hebben op het proces van inname of uitgifte. Om te Pagina 5 van 19

6 zien wat er aangeleverd moet worden of wat er uitgeleverd kan worden, heeft men de catalogus nodig. 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. Dataleveranciers Data-afnemers Gegevensdefinitie registratieobject Catalogus voor BRO Grondwatermonitoringput Beschrijving proces Innamehandboek voor BRO Grondwatermonitoringput Uitgiftehandboek voor BRO Grondwatermonitoringput Beschrijving technische realisatie Koppelvlakbeschrijving GMW Innamewebservice Koppelvlakbeschrijving GMW Uitgiftewebservice Figuur 1: Samenhang tussen documentatie 1.3 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 grondwatermonitoringputten. Hierbij wordt ingegaan op de keuzen die een data-afnemer moet maken als hij gegevens wil opvragen. Hoofdstuk 3 legt uit hoe het opvragen van gegevens via de webservice verloopt. Het hoofdstuk vertelt welke gegevens een data-afnemer moet meesturen met zijn verzoek en welke gegevens hij terug kan verwachten als antwoord. Pagina 6 van 19

7 Hoofdstuk 4 zal in de toekomst globaal uitleggen hoe het opvragen via DINOloket verloopt. Hoofdstuk 5 geeft een specificatie van de gegevens die nodig zijn om de uitgifte via de webservice goed te laten verlopen. 1.4 Versiehistorie Versie Datum Omschrijving 0.6 Augustus 2015 Versie tbv pilot projectfase Contactinformatie Voor vragen, suggesties of opmerkingen kunt u via info@dinoloket.nl contact opnemen met de servicedesk van de Basisregistratie ondergrond (BRO). Pagina 7 van 19

8 2 Uitgifte van gegevens 2.1 Twee manieren van uitgifte Iedereen mag gegevens opvragen uit de registratie ondergrond en men heeft daarbij de keuze uit twee mogelijkheden, via DINOloket of via een uitgiftewebservice. De verschillen tussen de twee zijn groot en wat de gebruiker kiest hangt af van de technische mogelijkheden waarover hij beschikt en van zijn informatiebehoefte. DINOloket is een website die toegang geeft tot de gegevens van alle registratieobjecten in de BRO. De gebruiker van het loket wordt stapsgewijze door het proces van uitgifte geleid. Hij kan op de website bepalen in welke objecten hij geïnteresseerd is, de belangrijkste gegevens daarvan bekijken en uiteindelijk besluiten van welke objecten hij gegevens wil opvragen. De opgevraagde gegevens worden hem vervolgens per toegestuurd. DINOloket is een laagdrempelige manier om gegevens uit de registratie ondergrond te krijgen. Een gebruiker die het loket gebruikt om gegevens te krijgen, een data-afnemer, hoeft bij het indienen van zijn aanvraag alleen zijn contactgegevens op te geven. De data-afnemer die gebruik maakt van de webservice moet zelf over een systeem beschikken dat geschikt is gemaakt voor het aanroepen van de webservice. Via de webservice worden de gegevens onmiddellijk geleverd. De data-afnemer die gebruik wil maken van de webservice moet zich eerst bij de BRO laten registreren om het gebruiksrecht te verkrijgen. De enige eis die daarbij wordt gesteld is dat de organisatie waar de dataafnemer werkt beschikt over een PKI-overheidscertificaat. 2.2 DINOloket of de uitgiftewebservice Uitgifte van gegevens is niet veel meer dan het verwerken van een verzoek tot de levering van bepaalde gegevens. Uitgifte lijkt daarmee een simpel proces maar, zoals gezegd, maakt het verschil of het DINOloket of de uitgiftewebservice wordt gebruikt. De verschillen beginnen al met de inhoud van het verzoek. Pagina 8 van 19

9 Voordat een gebruiker van DINOloket een verzoek tot levering van gegevens kan indienen moet hij een aantal keuzen maken. De website leidt de gebruiker stapsgewijze naar het indienen van het verzoek, en het is de gebruiker zelf die bepaalt wat hij allemaal uit de BRO geleverd wil krijgen 1. Wil hij bijvoorbeeld gegevens hebben van alle grondwatermonitoringputten en alle boor- en sondeeronderzoek in een bepaald gebied, dan kan hij dat allemaal tegelijk opvragen. Is hij in eerste instantie alleen geïnteresseerd in grondwatermonitoringputten, dan kan hij zich daartoe beperken. Het loket kan de belangrijkste gegevens van de objecten waarin de gebruiker geïnteresseerd is laten zien, en biedt ook het allerlei filtermogelijkheden om selecties te maken. Met dat soort functionaliteit kan de gebruiker desgewenst ook een heel gerichte keuze maken. Kortom, het scala aan keuzen dat DINOloket biedt is groot en dat betekent dat er een grote verscheidenheid aan verzoeken mogelijk is. De website zelf is zo gebouwd dat men eigenlijk geen fouten kan maken bij het invoeren van keuzen zodat er bij het verwerken van het verzoek niet veel controles meer nodig zijn. Opvragen van gegevens via de uitgiftewebservice kent minder vrijheidsgraden. Allereerst is er voor ieder type registratieobject een aparte webservice. Wil men gegevens van meer dan een type hebben, dan moet men verschillende webservices gebruiken. Een ander verschil is dat men de gegevens altijd in het IMBRO-XML formaat krijgt. Een derde verschil is dat het verzoek dat via de webservice wordt ingediend elementair is. De gebruiker kan of alle gegevens van een enkel registratieobject opvragen of een beperkte selectie van gegevens van een aantal registratieobjecten tegelijk. De reden die daarachter ligt is dat een webservice alleen in algemene gebruikerswensen voorziet. De meer specifieke wensen moeten afgehandeld worden door het systeem dat de data-afnemer gebruikt om de service aan te roepen. Dat systeem moet toegesneden zijn op de eisen die het bedrijfsproces van de data-afnemer stelt en de functionaliteit bieden die als aanvulling op de webservice gewenst is. Een laatste verschil is dat het proces van uitgifte bij het gebruik van de webservice strikt geformaliseerd is. De webservice verzorgt de communicatie tussen twee softwaresystemen en om 1 Gebruikt men het loket dan kan men naast gegevens uit de BRO ook gegevens uit het DINO-systeem opvragen, maar op dat aspect gaat dit handboek niet verder in. Pagina 9 van 19

10 te borgen dat de verwerking van een verzoek automatisch kan verlopen zijn er allerlei controles ingebouwd. 2.3 Uitgifte via de webservice Het proces van uitgifte via de webservice verdient nadere aandacht omdat het een generiek karakter heeft en voor alle registratieobjecten op gelijke wijze verloopt. Uitgifte van gegevens via de webservice is een proces dat onmiddellijk verloopt en slechts enkele stappen kent. Het eerste houdt in dat tussen het moment waarop een verzoek wordt ingediend en de levering van de gegevens vrijwel geen tijd verloopt. Dat het voor alle registratieobjecten op gelijke wijze verloopt, betekent dat uitgifte een vast patroon volgt. Het systeem van de data-afnemer doet een verzoek tot levering van gegevens, het systeem van de BRO beoordeelt het verzoek, het haalt de gegevens op en levert ze uit. Dat wil zeggen wanneer alles goed verloopt. Zit er een per ongeluk een fout in, dan wordt het verzoek door het systeem afgewezen. In alle gevallen krijgt het systeem van de data-afnemer een antwoord terug van de basisregistratie ondergrond. Data-afnemer Basisregistratie Ondergrond (BRO) Verzoek Systeem van de data-afnemer Antwoord op het verzoek Systeem van de BRO Figuur 2: Interactie tussen systeem van de data-afnemer en systeem van de BRO Een verzoek tot levering van gegevens is zoals gezegd elementair omdat het aansluit bij een standaard informatiebehoefte. De aanname is dat de gebruiker aanvankelijk niet precies weet welke objecten hij wil hebben en dat hij daarom eerst op zoek gaat naar de objecten die aan bepaalde criteria voldoen. Weet de gebruiker eenmaal welke objecten aan zijn criteria voldoen, dan kan hij alle gegevens per object opvragen. Vanuit dit perspectief ondersteunt de basisregistratie ondergrond de volgende typen verzoeken. Pagina 10 van 19

11 1. Een verzoek tot levering van de kengegevens van een aantal registratieobjecten. De data-afnemer geeft in zijn verzoek de eisen mee waaraan de registratieobjecten die hij zoekt moeten voldoen. In antwoord daarop krijgt hij van ieder van de objecten die aan de eisen voldoet de gegevens geleverd die het object karakteriseren. 2. Een verzoek tot levering van de gegevens van een bepaald registratieobject. De data-afnemer geeft in zijn verzoek het BRO-ID van het registratieobject dat hij wil hebben mee. In antwoord daarop krijgt hij alle gegevens van het object geleverd. Voor bepaalde typen registratieobject is er geen nuancering van dit type verzoek nodig. Dat zijn de objecten waarvan na registratie geen nieuwe gegevens meer aangeleverd worden. Geotechnisch sondeeronderzoek is daar een voorbeeld van. Andere typen registratieobject vertegenwoordigen een object waarvan de eigenschappen in de werkelijkheid kunnen veranderen. Die veranderingen worden geregistreerd en zo bouwt het object in de registratie ondergrond een geschiedenis op. De grondwatermonitoringput is een voorbeeld daarvan. Voor registratieobjecten met een geschiedenis, zijn er twee varianten van dit type verzoek: 2.1 Een verzoek tot levering van de actuele gegevens van een bepaald registratieobject. Als antwoord krijgt de data-afnemer alleen de gegevens die de actuele toestand beschrijven. 2.2 Een verzoek tot levering van de actuele en historische gegevens van een bepaald registratieobject. Als antwoord krijgt de dataafnemer alle gegevens van het object. Pagina 11 van 19

12 3 Opvragen van grondwatermonitoringputten via de webservice 3.1 Het formuleren van een verzoek Opvragen van grondwatermonitoringputten via de webservice verloopt geheel automatisch, maar het systeem van de dataafnemer moet wel een aantal dingen weten om de gegevens te kunnen opvragen. Om te beginnen moet het systeem weten wat voor type verzoek de data-afnemer wil indienen. Als de data-afnemer zijn keuze heeft gemaakt, weet het systeem welke functie van de service het moet gebruiken. De data-afnemer heeft de keuze uit drie typen verzoek. Grondwatermonitoringputten hebben namelijk eigenschappen die in de werkelijkheid kunnen veranderen. Het registratieobject bouwt dus een geschiedenis op en kent daarom verschil tussen actuele en historische gegevens. Heeft de data-afnemer een globaal idee van wat hij wil hebben en wil hij dus eerst op zoek naar de grondwatermonitoringputten die aan bepaalde eisen voldoen, dan zal hij kiezen voor een verzoek tot de levering van de kengegevens van grondwatermonitoringputten. Weet hij al precies welke grondwatermonitoringput hij wil hebben, dan vraagt hij om de levering van de gegevens van die grondwatermonitoringput. Hierbij moet de data-afnemer een keuze maken tussen de actuele gegevens of de actuele plus historische gegevens van het registratieobject. Voor de pilot is alleen de levering van de actuele gegevens van een grondwatermonitoringput in scope. Voor alle typen verzoeken moet de data-afnemer aangeven op welke kenmerken hij de levering wil baseren. Om de verwerking van een verzoek tot levering goed te laten verlopen moet de data-afnemer ook een eigen identificatie aan het verzoek meegeven. Wanneer de data-afnemer zijn keuzen aan het eigen systeem kenbaar heeft gemaakt kan het verzoek worden ingediend en begint de basisregistratie ondergrond met de verwerking. In de volgende paragrafen wordt de verwerking in meer detail beschreven en worden de inhoud van de berichten die worden uitgewisseld toegelicht. Pagina 12 van 19

13 3.2 Een verzoek tot levering van de actuele gegevens van een grondwatermonitoringput De verwerking van een verzoek tot levering van de gegevens van een grondwatermonitoringput 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 levering van de actuele gegevens van een grondwatermonitoringput. Daarbij geeft hij het BRO-ID mee waarop de levering moet worden gebaseerd. 2. Het systeem van de BRO voert een toegangscontrole uit. O Wanneer toegang wordt geweigerd, ontvangt (het systeem van) de data-afnemer daarvan een melding. 3. Wanneer toegang tot het systeem van de BRO is verkregen, begint de controle van het verzoek en wordt vastgesteld of het verzoek technisch en inhoudelijk aan de gestelde eisen voldoet. O Wanneer de controle fouten oplevert, wordt het verzoek afgewezen en ontvangt (het systeem van) de data-afnemer daarvan bericht. 4. Wanneer het verzoek correct is verzamelt het systeem van de BRO de actuele gegevens van de grondwatermonitoringput die aan het meegegeven BRO- ID voldoet. Vervolgens stuurt het BRO-systeem de dataafnemer als antwoord de opgevraagde gegevens. Het verzoek van de data-afnemer en het antwoord dat de BRO daarop geeft worden berichten genoemd. De stappen en de bijbehorende berichten worden in het onderstaande plaatje uitgebeeld. Pagina 13 van 19

14 Systeem van de data-afnemer Systeem van de BRO Stap 1: Doen van een verzoek tot levering Data-afnemer! Toegang geweigerd Stap 2: Uitvoeren toegangscontrole Verzoek tot levering Bericht van afwijzing Stap 3: Controleren verzoek Bericht van levering Stap 4: Verzamelen gegevens Verwerking Figuur 3: Verwerking van een verzoek tot levering van de actuele gegevens van een grondwatermonitoringput 3.3 De berichten Het verzoek tot levering Verzoek tot levering uw transactiekenmerk BRO-ID Het belangrijkste onderdeel van het verzoek tot levering van de actuele gegevens van de grondwatermonitoringput is het BRO- ID waarop de levering moet worden gebaseerd. Dit is de identificatie van het registratieobject waarvan de data-afnemer de actuele gegevens wil opvragen. Naast de kenmerken, moet de data-afnemer het verzoek een eigen identificatie meegeven en dat wordt uw transactiekenmerk genoemd. Het transactiekenmerk is nodig in de communicatie, bijvoorbeeld als er iets mis is gegaan en de data-afnemer daarover contact zoekt met de servicedesk Bericht van weigering! Toegang geweigerd Als bij het uitvoeren van de toegangscontrole blijkt dat de toegang moet worden geweigerd, ontvangt (het systeem van) de data-afnemer daarvan melding. Pagina 14 van 19

15 De toegangscontrole bestaat uit twee stappen: Het systeem van de BRO controleert of de dataafnemer daadwerkelijk is wie hij beweert te zijn. Hiervoor gebruikt de data-afnemer een soort van digitaal paspoort, het PKI-overheidscertificaat. Het systeem van de BRO controleert of de dataafnemer al het recht heeft gekregen voor het gebruik van de uitgiftewebservice voor grondwatermonitoringputten Bericht van afwijzing Bericht van afwijzing uw transactiekenmerk tijdstip van afwijzing Foutmelding Het bericht van afwijzing bestaat uit verschillende onderdelen. Het belangrijkste is de reden van afwijzing, de foutmelding. Het bericht van afwijzing bevat verder het tijdstip van afwijzing en een verwijzing naar het verzoek. Het bericht van afwijzing wordt gestuurd als de BRO tegen fouten aanloopt in het verzoek zelf. Deze controle dekt twee aspecten. Er wordt een technische controle uitgevoerd, en vervolgens vindt een inhoudelijke controle plaats van de gegevens die de data-afnemer mee heeft gegeven. De inhoudelijke controle betreft in dit geval alleen het transactiekenmerk en het BRO-ID. De controle is eenvoudig: de twee gegevens moeten aan de specificaties (zie hoofdstuk 5) voldoen. Foutmeldingen die op technische fouten betrekking hebben zijn alleen bedoeld voor programmeurs en worden uitgebreid behandeld in de koppelvlakbeschrijving. Fouten in de gegevens die de data-afnemer heeft meegegeven kunnen juist ook voor hem van belang zijn. In zo n foutmelding wordt van iedere fout opgenomen - bij welk gegeven de fout is geconstateerd - wat eventueel de waarde van het gegeven is - wat de fout is Pagina 15 van 19

16 3.3.4 Bericht van levering Bericht van levering uw transactiekenmerk tijdstip van uitgifte De actuele gegevens van de grondwatermonitoringput Het bericht van levering bestaat ook weer uit verschillende onderdelen. Het belangrijkste zijn de gegevens die zijn opgevraagd. Het bericht van levering bevat verder een verwijzing naar het verzoek tot levering en het tijdstip waarop de gegevens zijn uitgegeven. Welke gegevens er precies worden uitgegeven hangt in de eerste plaats af van de vraag of de data-afnemer ook de bronhouder of de dataleverancier van de betreffende grondwatermonitoringput is. De bronhouder en de dataleverancier 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 niet alle gegevens. Wat zij krijgen hangt af van de vraag of een object uit registratie is genomen. Normaliter krijgen deze gewone data-afnemers alle gegevens van de grondwatermonitoringput geleverd op vijf na. De vijf gegevens die ze niet geleverd krijgen zijn: Entiteit Grondwatermonitoringput Aangeleverde positie Monitoringbuis Attribuut dataleverancier onderhoudende instantie object-id bronhouder uitvoerder horizontale plaatsbepaling uitvoerder verticale plaatsbepaling uitvoerder bepaling posities In het uitzonderlijke geval dat het registratieobject uit registratie is genomen, krijgen de gewone data-afnemers alleen de volgende gegevens: Entiteit Grondwatermonitoringput Registratiegeschiedenis Attribuut BRO-ID uit registratie genomen Pagina 16 van 19

17 tijdstip uit registratie genomen Tot slot kan het voorkomen dat de data-afnemer een BRO-ID heeft opgegeven dat niet bestaat. In dat geval ontvangt hij een bericht van levering waarin het element met gegevens van de grondwatermonitoringput leeg is. Pagina 17 van 19

18 4 Opvragen van grondwatermonitoringputten via het DINOloket Dit hoofdstuk is in deze versie van het uitgiftehandboek niet uitgewerkt. Pagina 18 van 19

19 5 Specificatie van de berichtgegevens bij uitgifte via de webservice 5.1 Inleiding Bij uitgifte via de webservice horen verschillende typen berichten. De opbouw van de berichten is besproken in hoofdstuk 3 en de elementen die daarin zijn genoemd worden in dit hoofdstuk gespecificeerd. Uitzondering daarop zijn de twee elementen die de gegevens omvatten die opgevraagd worden en die de essentie vormen van een bericht van levering. 5.2 Attributen en entiteiten 1. Naam attribuut uw transactiekenmerk Definitie Kardinaliteit 1-1 Domein Een kenmerk dat de data-afnemer meegeeft om het verzoek tot levering te identificeren. Tekst Maximale lengte 200 Naam attribuut Definitie Kardinaliteit 1-1 Domein Type Opbouw Regels - BRO-ID De identificatie van een object dat in de registratie ondergrond is opgenomen. Registratieobjectcode Code CPTNNNNNNNNNNNN Naam entiteit Definitie Domein Regels - Foutmelding De verzameling van foutomschrijvingen die onderdeel zijn van een bericht van afwijzing. Foutomschrijving Pagina 19 van 19