Basisregistratie Ondergrond (BRO) Koppelvlakbeschrijving

Basisregistratie Ondergrond (BRO) Koppelvlakbeschrijving GMW Innamewebservice

Datum Status

19 augustus 2015 0.6

BRO-Koppelvlakbeschrijving GMW Innamewebservice – versie 0.6

Colofon Bestuurskern Dir. Ruimtelijke Ontwikkeling Plesmanweg 1-6 Den Haag Algemeen contact

Programmabureau BRO Directoraat-Generaal Ruimte en Water [email protected]

Versie

0.6

Auteur

TNO Geologische Dienst Nederland

Pagina 3 van 50


Inhoudsopgave

1

Inleiding ............................................. 6 1.1

Doel en doelgroep koppelvlakbeschrijving ..........6

1.2

Samenhang met andere documentatie ................ 6

1.3

Leeswijzer...........................................................7

1.4

Versiehistorie......................................................8

1.5

Contactinformatie ...............................................8

2 Uitwisselen van gegevens via de webservice ................................................ 9 2.1

Het koppelvlak ....................................................9

2.2

De realisatie van het koppelvlak .......................10

2.3

Verwerking van een verzoek door de webservice 10

2.4 BRO

Gemaakte keuzes voor de webservices van de 11

3 Inname van grondwatermonitoringputten via de webservice .............................................. 14 3.1

Opbouw van het koppelvlak van de BRO ...........14

3.2

De WSDLs van de BRO ......................................14

3.3

De verwerking van een registratieverzoek ........16

3.4

De verwerking van een aanvullingsverzoek ......18

3.5

De verwerking van een beëindigingsverzoek ....18

3.6

Controles ..........................................................21

4 Specificatie berichten voor innametransacties grondwatermonitoringputten .................. 24 4.1

Inleiding ...........................................................24

4.2 De berichten die bij registratie worden uitgewisseld .................................................................25

Pagina 4 van 50


4.3 De berichten die bij aanvulling worden uitgewisseld .................................................................27 4.4 De berichten die bij beëindiging worden uitgewisseld .................................................................28

5 Specificatie van de gegevens van grondwatermonitoringputten die kunnen worden aangeboden ................................ 31

6

5.1

RegistrationObject GroundwaterMonitoringWell Error! Bookmark not defined.

5.2

Registratiedocument .........................................32

5.3

Aanvullingsdocument ........................................32

5.4

Beëindigingsdocument ......................................39

Uitwerking specifieke elementen ..... 40

Bijlages ................................................... 44 Bijlage A: Vertaalslag Engels – Nederlands ..................44 Bijlage B: Achtergrond bij de techniek rondom het koppelvlak ...................................................................47

Pagina 5 van 50


1

Inleiding

1.1

Doel en doelgroep koppelvlakbeschrijving Deze koppelvlakbeschrijving geeft een beschrijving van het technische koppelvlak voor het aanbieden van grondwatermonitoringputten aan de Basisregistratie ondergrond. Het document richt zich voornamelijk op de technisch specialisten die de aansluiting gaan realiseren tussen de systemen van dataleveranciers en het systeem van de BRO. Kennis van XML en webservices is benodigd om deze aansluiting daadwerkelijk te bouwen op basis van dit document. Het is echter zo geschreven dat overige belangstellenden met beperkte kennis op dit vlak de strekking van de aansluiting kunnen volgen.

1.2

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. In de catalogus staan de definities van alle entiteiten en attributen van het registratieobject beschreven. Ook staan in de catalogus de kardinaliteit (het aantal keer dat de entiteit of het attribuut voorkomt), regels voor het gebruik en de toegestane waardes voor de attributen. Ook de samenhang tussen de entiteiten wordt beschreven. De catalogus beschrijft dus de inhoud van de BRO en vormt de basis voor de andere 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 innemen of uitgeven. Om te 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

Pagina 6 van 50


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.

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 deze koppelvlakbeschrijving. Hoofdstuk 2 geeft een inleiding op de uitwisseling van gegevens via de webservices van de BRO. Dit hoofdstuk is bedoeld voor de lezer die een globaal idee wil krijgen van de technische werking van de BRO. Hoofdstuk 3 geeft de technische specificaties voor de inname van grondwatermonitoringputten. Dit hoofdstuk is bedoeld voor de lezer die de specifieke technische werking van de BRO voor inname van grondwatermonitoringputten wil begrijpen en de keuzes die daarbij zijn gemaakt. Dit hoofdstuk gaat echter nog niet in op alle details. Hoofdstuk 4 en hoofdstuk 5 geven de specificaties van respectievelijk het XML Schema voor de innametransacties voor grondwatermonitoringputten en het XML Schema voor grondwatermonitoringput. Deze hoofdstukken maken het samen

Pagina 7 van 50


met de kennis uit hoofdstuk 3 mogelijk voor de lezer om aan te sluiten op de BRO en geeft daarvoor alle benodigde details. In hoofdstuk 6 staat een uitwerking van specifieke elementen uit de twee XML Schema’s. 1.4 Versie 0.6

1.5

Versiehistorie Datum Augustus 2015

Omschrijving Versie ten behoeven van pilot GMW Fase 1

Contactinformatie Voor vragen, suggesties of opmerkingen kunt u via [email protected] contact opnemen met de servicedesk van de Basisregistratie Ondergrond (BRO).

Pagina 8 van 50


2

Uitwisselen van gegevens via de webservice

2.1

Het koppelvlak Dit hoofdstuk geeft een inleiding op berichtuitwisseling. De Basisregistratie Ondergrond voorziet in een koppelvlak waarmee dataleveranciers op een geautomatiseerde manier gegevens aan de BRO kunnen overdragen. Systemen van data-leveranciers sluiten via het koppelvlak aan op de systemen van de BRO.

Figuur 2: Aansluiting op het BRO systeem via een koppelvlak

Zoals hierboven al beschreven, kan via een koppelvlak overdracht van gegevens plaatsvinden. Deze overdracht van gegevens wordt een transactie genoemd. Wanneer het gaat om overdracht van gegevens door een dataleverancier aan de BRO wordt gesproken over een innametransactie, als het een overdracht van gegevens door de BRO aan data-afnemers betreft wordt dit een uitgiftetransactie genoemd.

Figuur 3: Een transactie tussen data leverancier/afnemer en de BRO

Pagina 9 van 50


2.2

De realisatie van het koppelvlak Het koppelvlak zoals hierboven beschreven kan op verschillende manieren worden gerealiseerd. De BRO kent voor het aanbieden van registratieobjecten twee manieren, namelijk via het loket of via de webservice. Dit document richt zich enkel op het in technische termen beschrijven van het koppelvlak dat is gerealiseerd door middel van webservices. De keuzes voor de inrichting van de BRO zijn gebaseerd op de NORA (Nederlandse Overheid Referentie Architectuur) en de Digikoppeling specificaties. Het koppelvlak is gerealiseerd met W3C webservices. Hiermee kan een extern systeem, een cliëntsysteem genoemd, via een request-response mechanisme communiceren met het systeem van de BRO. Deze communicatie vindt plaats over het internet. De belangrijkste concepten die een rol spelen bij de webservices van de BRO zijn WSDL en SOAP.

Figuur 4: De positie van WSDL en SOAP bij een transactie

2.3

Verwerking van een verzoek door de webservice Als een dataleverancier of data-afnemer gegevens wil uitwisselen met de BRO moet hij hiervoor altijd zelf het initiatief nemen. Om een transactie te starten moet vanuit het systeem van de dataleverancier of data-afnemer ten eerste een verzoek (request genoemd) worden verstuurd aan de webservice van het BROsysteem. Dit verzoek bestaat uit een SOAP-bericht waarin is aangegeven welke transactie uitgevoerd moet worden. De invoergegevens die voor deze transactie moeten worden gebruikt worden ook gelijk meegegeven. Het systeem van de BRO reageert op dit verzoek door middel van een antwoord, (response genoemd). Aangezien het bij de BRO om synchrone webservice gaat, bevat de response direct het resultaat van de transactie, opnieuw in de vorm van een SOAP bericht.

Pagina 10 van 50


Afhankelijk van de verwerking door de BRO verschilt de inhoud van deze response.

Figuur 5: Request-response mechanisme

2.4

Gemaakte keuzes voor de webservices van de BRO

2.4.1

Communicatiestandaarden Voordat deze standaarden verder worden toegelicht, wordt hieronder het complete plaatje voor uitwisseling geschetst. De communicatie tussen het systeem van de dataleverancier en het systeem van de BRO verloopt namelijk over een aantal lagen. Voor elk van de lagen staat hieronder weergegeven welke standaarden gebruikt zijn. Dit geeft een beeld waar het hierboven beschreven mechanisme en bijbehorende standaarden op het niveau van de uitwisseling van berichten zich bevinden in het grotere geheel. Ook is de positie van de BRO weergegeven. In bijlage B staat meer achtergrondinformatie over de techniek rondom het koppelvlak.

Inhoud

}

Digikoppeling

Logistiek

Transport

Semantiek

XML Schema

Structuur

XML

Service beschrijving

WSDL

Berichtuitwisseling

SOAP

Transportprotocol

HTTP

Netwerk

TCP/IP

Pagina 11 van 50

}

BRO


Figuur 6: Raamwerk voor uitwisselbaarheid

2.4.1.1

SOAP Het Simple Object Access Protocol (SOAP) is een protocol voor het versturen van XML berichten. Het doel van SOAP is het uitwisselen van data over netwerken en daarom houdt het zich bezig met het inkapselen en coderen van XML data en het definiëren van regels voor het versturen en ontvangen van die data. Een SOAP bericht is niet bedoeld voor menselijke interpretatie, maar worden door het ontvangende systeem verwerkt. Het systeem van de BRO maakt gebruik van SOAP 1.1.

2.4.1.2

WSDL Bij elk koppelvlak dat is gerealiseerd door middel van een W3C webservice hoort een WSDL (Web Service Definition Language) document. Dit document, beschreven in XML, beschrijft in technische termen welke transacties er mogelijk zijn via de webservice. Onder andere staat gedefinieerd hoe men toegang kan krijgen tot de service en welke gegevens moeten worden ingevoerd en welke kunnen worden terugverwacht van het systeem. Het systeem van de BRO maakt gebruik van WSDL 1.0.

2.4.2

Synchrone webservices Er bestaan synchrone en asynchrone webservices. Bij een synchrone webservice wacht het systeem dat het verzoek heeft verstuurd tot er een antwoord ontvangen is. Wanneer een verzoek enige verwerkingstijd vergt bij het ontvangende systeem (in dit geval het systeem van de BRO), blijven de resources bij de aanvrager voor dit verzoek in gebruik en kan er dus maar een beperkt aantal transacties tegelijk worden verwerkt. Het gevolg kan zijn dat een gebruiker geen transacties kan starten en moet wachten tot er resources zijn vrijgekomen. De BRO volgt hierin de Best Effort variant van Digikoppeling. Deze variant schrijft voor dat de uitwisseling synchroon plaatsvindt, maar vereist geen faciliteiten voor betrouwbaarheid, zoals ontvangstbevestigingen en het elimineren van duplicaten.

Pagina 12 van 50


Op dit moment is er binnen de BRO voor gekozen enkel synchrone webservices te implementeren. Waar niet direct een antwoord kan worden gegeven, wordt via de mail een reactie gestuurd. 2.4.3

Gebruikte standaarden en hun namespaces De XML Schema’s van de BRO zijn gebaseerd op domeinmodellen voor de verschillende registratieobjecten. Deze domeinmodellen staan conceptueel en inhoudelijk volledig beschreven is in de catalogus van het registratieobject. Waar het domeinmodel onafhankelijk van implementatiekeuzes is beschreven, is bij de uitwerking naar het XML Schema juist wel rekening gehouden met nationale en internationale technische standaarden. XML Schema’s van de BRO maken doorgaans dan ook gebruik van de volgende standaarden: • NEN 3610:2010, Basismodel Geoinformatie • OpenGIS® Geography Markup Language (GML) Encoding Standard, OGC 07-036 De relatie tussen het domeinmodel en het XML Schema is zo veel mogelijk 1-op-1 gehouden. Door de toepassing van internationale standaarden wordt echter een aantal elementen, types en attributen in het XML Schema geïntroduceerd die niet zijn opgenomen in het domeinmodel. De consequenties die dit heeft staan expliciet benoemd bij de elementen die als gevolg van het toepassen van standaarden een andere invulling hebben dan verwacht. Daarnaast is het XML Schema conform de internationale standaarden uitgewerkt in het Engels, waar het domeinmodel in het Nederlands beschreven is. De toepassing van internationale standaarden betekent dat in de XSD wordt gerefereerd aan de XML Schema’s, die bij die standaarden horen. In de WSDL en de SOAP berichten van de webservices van de BRO worden de volgende standaarden gebruikt met bijbehorende namespaces. In de laatste kolom staat een prefix voor elke namespace. Deze prefixen mogen echter zelf worden gekozen, dit is enkel het prefix dat in de voorbeelden wordt gebruikt.

Pagina 13 van 50


3

Inname van grondwatermonitoringputten via de webservice

3.1

Opbouw van het koppelvlak van de BRO Voor elk registratieobject ontwikkelt de BRO voor zowel inname als uitgifte een WSDL. De invoer- en uitvoergegevens voor elke operation in de WSDL worden beschreven in een ‘berichten’-XSD. Deze ‘berichten’-XSD wordt geïmporteerd in de WSDL en maakt weer gebruik van een XSD die het registratieobject zelf beschrijft. Daarnaast gebruikt de ‘berichten’-XSD de gemeenschappelijke standaarden, welke in hoofdstuk 2.4.3 genoemd staan. De WSDL voor de inname van grondwatermonitoringputten is isgmw.wsdl. De bijbehorende ‘berichten’-XSD is isgwmmessages.xsd. De XSD die de grondwatermonitoringput zelf beschrijft is gmwcommon.xsd. In onderstaande figuur is de relatie tussen de WSDL en deze XML Schemas weergegeven.

Figuur 7: De relatie tussen de WSDL's en XML Schema's

De specifieke namespaces voor de genoemde XML Schema’s voor grondwatermonitoringputten staan hieronder benoemd. Specificatie Gemeenschappelijke BRO types GroundwaterMonitoring Well Innametransacties GroundwaterMonitoring Well Geography Markup

Namespace URI http://www.broservices.nl/xsd/ brocommon/2.3 http://www.broservices.nl/xsd/ gmwcommon/0.6 http://www.broservices.nl/xsd/isgmw/ 0.6

Prefix brocom

http://www.opengis.net/gml/3.2

gml

Pagina 14 van 50

gmwcommon isgmw


Language 3.2 XML Schema instance XML Linking Language 3.2

http://www.w3.org/2001/ XMLSchema-instance http://www.w3.org/1999/xlink

xsi xlink

De WSDLs van de BRO De service met daarbij de port beschrijft hoe men toegang krijgt tot de service De service voor inname van grondwatermonitoringputten: - Service name: isgmw - Port name: isgmw_SOAP - SOAP address location: https://www.broservices.nl/wsdl/isgmw//isgmw/v<<x.y >>

Een binding geeft details over het transport behorende bij een port, onder andere het communicatieprotocol en het formaat van de input en de output. De BRO geeft alleen binding voor SOAP 1.1, ‘document-literal wrapped’ en als transport binding http. Voor elke operation is de style ‘document’ en de input en output use ‘literal. De binding voor inname van grondwatermonitoringputten: - Binding name: isgmw_SOAP - SOAP operation SOAP action: “” (lege string)

Port type specificeert de interface en legt in operations de structuur van de input en output berichten vast. Elk van de transacties die in het innamehandboek gedefinieerd staat wordt gerealiseerd door één van deze operations. isgmw.wsdl kent de volgende operations in port type: - registerGMW - additionGMWOwner - additionGMWTubeLength - additionGMWTubeStatus - additionGMWMaintainanceResponsibleParty - additionGMWWellHeadProtectionTubeLength - additionGMWWellHeadProtection - additionGWMRepairTube - additionGMWGroundlevel - additionGMWWellPosition - additionGMWTubePosition - completeRegistrationGMW

Pagina 15 van 50


Messages beschrijven de berichten die per transactie worden uitgewisseld, uitgedrukt in parts (XML elementen). Er is steeds sprake van een request en een reponse. De naam van de bijbehorende operation is onderdeel van naam van het request en de response. De inhoud van de response is afhankelijk van de verwerking van het verzoek tot levering, zie verder paragraaf 3.3. isgmw.wsdl kent de volgende messages: - registerGMWRequest - registerGMWResponse - additionGMWOwnerRequest - additionGMWOwnerResponse - additionGMWTubeLengthRequest - additionGMWTubeLengthResponse - additionGMWTubeStatusRequest - additionGMWTubeStatusResponse - additionGMWMaintainanceResponsiblePartyRequest - additionGMWMaintainanceResponsiblePartyResponse - additionGMWWellHeadProtectionTubeLengthRequest - additionGMWWellHeadProtectionTubeLengthResponse - additionGMWWellHeadProtectionRequest - additionGMWWellHeadProtectionResponse - additionGWMRepairTubeRequest - additionGWMRepairTubeResponse - additionGMWGroundlevelRequest - additionGMWGroundlevelResponse - additionGMWWellPositionRequest - additionGMWWellPositionResponse - additionGMWTubePositionRequest - additionGMWTubePositionResponse - completeRegistrationGMWRequest - completeRegistrationGMWResponse

Een type bevat XML Schemas met daarbinnen XML types en elementen. Deze XML Schemas kunnen extern worden gedefinieerd en worden geïmporteerd. isgmw.wsdl kent het volgende type: - http://www.broservices.nl/xsd/imbroisgmw/1.1.0/isgmw-messages

3.3

De verwerking van een registratieverzoek Hieronder staat uitgewerkt hoe de webservice een registratieverzoek verwerkt. Elk van de genoemde messages in paragraaf 3.2 die van toepassing is op registratie is terug te vinden in onderstaande afbeelding.

Pagina 16 van 50


Figuur 8: De verwerking van een registratieverzoek

Pagina 17 van 50


3.4

De verwerking van een aanvullingsverzoek Een aanvullingsverzoek wordt door de webservice op gelijke manier verwerkt als een registratieverzoek. Elk van de genoemde messages in paragraaf 3.2 die van toepassing is op aanvulling is terug te vinden in onderstaande afbeelding.

Figuur 9: De verwerking van een aanvullingsverzoek

3.5

De verwerking van een beëindigingsverzoek Een beëindigingsverzoek wordt door de webservice op gelijke manier verwerkt als een registratieverzoek. Elk van de genoemde messages in paragraaf 3.2 die van toepassing is op beëindiging is terug te vinden in onderstaande afbeelding.

Pagina 18 van 50


Figuur 10: De verwerking van een beëindigingsverzoek

Pagina 19 van 50


3.6

Controles

3.6.1

Toegangscontrole Voor de beveiliging van de transacties die plaatsvinden tussen een dataleverancier en de BRO worden PKIoverheid certificaten gebruikt. Zowel de dataleverancier als de BRO beschikt over een dergelijk certificaat. In het certificaat is een identificatie opgenomen die uniek is voor de houder van het certificaat. Omdat deze identificatie cruciaal is voor de beveiliging, wordt de identiteit van de aanvrager van een PKIoverheid certificaat streng gecontroleerd. Op het moment dat een systeem van een dataleverancier of afnemer een transactie initieert, wisselen dit systeem en het BRO systeem eerst hun PKIoverheid certificaten uit. Aan de hand van de identificatie in de certificaten weten beide partijen met wie de transactie wordt opgezet (authenticatie). Als de authenticatie succesvol is verlopen dan worden beide certificaten vervolgens gebruikt om al het dataverkeer tussen de systemen te versleutelen (via TLS of SSL). Deze versleuteling maakt het voor derden onmogelijk om de data te lezen of te wijzigen. Elke transactie met de BRO mag alleen worden uitgevoerd door een systeem van een dataleverancier of data-afnemer dat daarvoor het recht heeft gekregen van de BRO. Aan de hand van de identificatie in het certificaat wordt door de BRO bepaald of dit systeem het recht heeft om de transactie uit te voeren (autorisatie). De rechten van de gebruiker worden beheerd door de BRO. Als de toegangscontrole tot een fout leidt, ontvangt de dataleverancier de melding met een HTTP statuscode.

3.6.2

Gegevenscontrole Het XML document dat in de body van het SOAP bericht wordt meegegeven wordt gecontroleerd op basis van het XML Schema waar het naar verwijst. Het XML Schema legt regels vast over de structuur van het XML document en gegevens zelf, dus de ingevulde waardes in het XML document, controleren. Het XML Schema legt namelijk vast: • Welke gegevens verplicht zijn • Welk type een ingevulde waarde moet hebben Een XML Schema kan echter geen regels vastleggen die gelden tussen verschillende gegevens. Het vastleggen en controleren van dit soort regels, business rules genoemd, gebeurt door

Pagina 21 van 50


middel van de programmatuur aan de kant van de BRO. Voorbeelden van dit soort controles zijn: • Welke lengte een ingevulde waarde moet hebben • Wat de toegestane waardes zijn voor een gegeven Voor innametransacties geldt dat dit soort gegevenscontroles worden uitgevoerd op de transactiegegevens die zijn meegegeven en daarnaast wordt het brondocument dat wordt aangeboden ook op een dergelijke manier inhoudelijk gecontroleerd. Naast de inhoudelijke controle van de transactiegegevens vindt er ook een technische controle van het verzoek plaats. Dit betekent onder andere dat wordt nagegaan of het protocol dat gebruikt is in het verzoek juist is. Nadat de technische controle heeft plaatsgevonden wordt het verzoek in het systeem van de BRO getransformeerd van XML naar Java.

3.6.3

Controle op rechten Het systeem controleert of de dataleverancier die het innameverzoek doet bij de BRO geregistreerd is als bronhouder van grondwatermonitoringputten, of dat bij de BRO bekend is dat de dataleverancier grondwatermonitoringputten mag aanleveren voor deze bronhouder. Pas daarna wordt het brondocument inhoudelijk gecontroleerd. Als de inhoudelijke controle van het brondocument slaagt, bekijkt het systeem daarna de organisaties en hun rollen die genoemd worden in het brondocument. Hierbij wordt gecontroleerd of de genoemde bronhouder en uitvoerder reeds bekend zijn in de BRO. Tot slot wordt gecontroleerd of de inhoud van het brondocument overeenkomt met het kwaliteitsregime dat als transactiegegeven is meegegeven in het innameverzoek.

3.6.4

Aanvullende controles op aanvullings- en beëindigingsdocumenten Aanvullingsdocument: Naast de eerder beschreven controles kunnen aanvullende controles worden uitgevoerd op basis van validatieregels die gelden voor een specifiek aanvullingsbrondocument. Deze controles vallen uiteen in twee typen: • Aanvullende controles op gegevens binnen het aanvullingsbrondocument

Pagina 22 van 50


•

Aanvullende controles op een bepaald gegeven uit het aanvullingsbrondocument aan de hand van actuele waarde van dat gegeven in de registratie ondergrond.

Pagina 23 van 50


4

Specificatie berichten voor innametransacties grondwatermonitoringputten

4.1

Inleiding Voor de inname van grondwatermonitoringputten is één XMLschema (XSD) gemaakt op basis van de specificaties uit het Innamehandboek voor BRO Grondwatermonitoringput. Hieronder staan alle berichten die worden uitgewisseld bij specifieke transacties. Ten eerste is voor elk bericht de specificatie uit het innamehandboek naast de structuur uit het XML bericht weergegeven. Daarna volgt voor elk bericht een voorbeeld. Zoals te zien is in de voorbeelden is in het XML Schema gebruik gemaakt van Engelse termen. De vertaalslag van de Engelse termen zoals gebruikt in het XML Schema naar de Nederlandse termen zoals gebruikt in het innamehandboek is in bijlage A te vinden. In de eerste kolom van dit voorbeeld staat voor een aantal elementen een referentie. Als er geen referentie in de eerste kolom staat, betekent het dat het element exact uitgewerkt is zoals in het innamehandboek gespecificeerd staat. Staat er wel een referentie? Een numerieke referentie verwijst dan naar een verdere uitwerking van het element in een hoofdstuk verderop. Een tekstuele referentie verwijst dan naar een verdere toelichting op het element, aangezien deze afwijkt of uitgebreider is dan gespecificeerd in het innamehandboek.

Pagina 24 van 50


4.2

De berichten die bij registratie worden uitgewisseld 4.2.1

Het registratieverzoek

levering120150728 IMBRO/A

4.2.2

Bericht van afwijzing

eigenaar120150729 A-GMW-201507290000-000003 2015-07TIME 29T11:33:24+02:00 30277172 30277172 IMBRO/A

Pagina 25 van 50


(Foutmelding)

4.2.3

Bericht van verwerking

levering120150728 R-GMW-20150728-0000-000021 < brocom:broId>GMW000000133602 2015-07TIME 28T11:31:24+02:00 2005-07TIME 28T11:31:24+02:00 25H010001 30277172 IMBRO/A CWA

Pagina 26 van 50


4.3

De berichten die bij aanvulling worden uitgewisseld 4.3.1

Het aanvullingsverzoek

eigenaar120150729 IMBRO/A (specifiek aanvuldocument) 5.2

4.3.2


eigenaar120150729 A-GMW-201507290000-000003 GMW000000013561 2015-07TIME 29T11:33:24+02:00 30277172 IMBRO/A (Foutmelding)

Pagina 27 van 50


4.3.3


Bericht van verwerking uw transactiekenmerk Verwijzing naar het BRO transactiekenmerk registratieverzoek kwaliteitsregime BRO-ID bronhouder tijdstip laatste aanvulling

AdditionGMWResponse yourTransactionReference Verwijzing naar het broTransactionReference registratieverzoek broId latestAdditionTime deliveryAccountableParty qualityRegime

eigenaar120150729 A-GMW-201507290000-000003 GMW000000013561 2005-07TIME 29T11:33:24+02:00 30277172 IMBRO/A

4.4

De berichten die bij beëindiging worden uitgewisseld 4.4.1

5.3

Het beëindigingsverzoek

opgeruimd juni 2015 p12 (beëindigingsdocument)

Pagina 28 van 50


4.4.2


opgeruimd juni 2015 p12 A-GMW-201507290000-000003 GMW000000013561 2015-07TIME 29T11:33:24+02:00 30277172 IMBRO/A (Foutmelding)

4.4.3


Pagina 29 van 50


opgeruimd juni 2015 p12 A-GMW-201507290000-000003 GMW000000013561 2015-07TIME 29T11:33:24+02:00 30277172 IMBRO/A

Pagina 30 van 50


5

Specificatie van de gegevens van grondwatermonitoringputten die kunnen worden aangeboden

De brondocumenten van grondwatermonitoringputten die kunnen worden aangeboden staan hieronder verder uitgewerkt aan de hand van voorbeelden. Er is een drietal varianten van brondocumenten die kunnen worden aangeboden te vinden: - Het registratiedocument - Het aanvullingsdocument - Het beëindigingsdocument Deze brondocumenten zijn gebaseerd op het registratieobject grondwatermonitoringput dat wordt vastgelegd in de Basisregistratie ondergrond. Het registratieobject staat daarom eerst uitgewerkt en daaronder volgen de brondocumenten die hiervan zijn afgeleid. In de eerste kolom van de voorbeelden staat voor een aantal elementen een referentie. Als er geen referentie in de eerste kolom staat, betekent het dat het element exact uitgewerkt is zoals in de catalogus gespecificeerd staat. Staat er wel een referentie? Een numerieke referentie verwijst dan naar een verdere uitwerking van het element in een paragraaf verderop. Een tekstuele referentie verwijst dan naar een verdere toelichting op het element, aangezien deze afwijkt of uitgebreider is dan gespecificeerd in de catalogus. In de XML Schema’s en dus ook in de XML voorbeelden wordt gebruik gemaakt van Engelse termen. De vertaalslag van de Engelse termen zoals gebruikt in het XML Schema naar de Nederlandse termen zoals gebruikt in de catalogus is in Bijlage A.

Pagina 31 van 50


5.1

Registratiedocument De dataleveranciers bieden bij een registratie in principe alle gegevens van het registratieobject grondwatermonitoringput aan, op de volgende gegevens na: Entiteit GroundwaterMonitoringWell (5.1)

Attribuut broId qualityRegime deliveryResponsibleParty

Zoutwachter

inUse

MonitoringTube

inUse

RegistrationHistory

Geheel

StandardizedLocation

Geheel

5.1.1 ID

CWA

CWA

CWA

CWA CWA DATE DATE 5.1.2 5.1.5 5.1.6 5.1.7

Brondocument registerGMW 30277172 rechtsgrondWaterwet vdWeeteringsPut1 STOWA Handboek 05069581 beschermkokerStaal ja monitoringGrondwaterstand 2014-11-04+01:00 2014-11-04+01:00 ... ... ... ... 25H01000 09122561 09122561

Pagina 32 van 50


5.1.2 ID

CWA CWA

CWA CWA MEA NIL MEA CWA

5.1.3 5.1.4

5.1.3 CWA MEA NIL MEA MEA

5.1.4 ÇWA

MEA NIL MEA MEA

5.1.5 ID

MonitoringTube 1 buis ja ja klaarvoorGebruik 10 -0.98 DGPS01_025m 09122561 ...> ...

Screen pvc 36 10.48 10.98

OtherTubePart pvc 36 0.98 9.48

DeliveredLocation 134750 477800 landmetingGr01m 09122561

DeliveredVerticalPosition maaiveld 0.000 1.2 DGPS01_025m 09122561 NAP

OhmTester 1 ...

ElectrodePair 1 9.15 20 zand

Aanvullingsdocument 5.2.1

Brondocument additionGMWOwner GMW000000013561 30277172

Pagina 34 van 50


DATE

2015-07-29 05069582

5.2.2

Brondocument additionGMWTubeLength GMW000000013561

DATE

CWA

CWA

5.2.3

30277172 2015-07-29 1 ja NAP 1 1.000 1.000 DGPS01_025m 09122561

Brondocument additionGMWTubeStatus GMW000000013561

DATE CWA

5.2.4

30277172 2015-07-29 1 klaarvoorgebruik

Brondocument additionGMWMaintainanceResponsibleParty GMW000000013561

DATE

30277172 2015-07-29 30277173

Pagina 35 van 50


5.2.5

Brondocument additionGMWWellHeadProtectionAndTubeLength GMW000000013561

DATE CWA CWA

CWA

CWA

30277172 2015-07-29 1 ja NAP beschermkoker 1.000 1.000 1.000 DGPS01_025m 30277172

5.2.6

Brondocument additionGMWWellHeadProtection GMW000000013561

DATE CWA

5.2.7

30277172 2015-07-29 beschermkoker

Brondocument additionGWMTubeRepair GMW000000013561

DATE CWA

CWA

30277172 2015-07-29 1 nee 1.000 NAP 1.000

Pagina 36 van 50


CWA

CWA

1.000 teflon 13 DGPS01_025m 30277172

5.2.8

Brondocument additionGMWGroundlevel GMW000000013561

DATE CWA

CWA

30277172 2015-07-29 NAP 1.000 DGPS01_025m 09122561

5.2.9

DATE CWA CWA

CWA

CWA

Brondocument additionGMWWellPosition GMW000000013561 2015-07-29 NAP NAP 30277172 5.120 DGPS01_025m 09122561 001 ja 5.670

Pagina 37 van 50


7.330 -8.330 5.670 3.670 3.670 -6.330 -6.330 -7.330 -8.330 -9.830

5.2.10

Brondocument additionGMWTubePosition GMW000000013561

DATE

CWA

CWA

30277172 2015-07-29 1 ja 5.670 7.330 -8.330 5.670 3.670 3.670 -6.330 -6.330 -7.330 -8.330 -9.830 DGPS01_025m 09122561
Pagina 38 van 50


ngOperator>

5.3

Beëindigingsdocument 5.3.1

CompleteRegistrationGMW GMW000000013561 30277172

DATE

2015-07-29

Pagina 39 van 50


6

6.1

Uitwerking specifieke elementen

CWA

CWA

Element van het type gml:CodeWithAuthority Dit element kan alleen een waarde bevatten uit in een codelijst. Het codeSpace attribuut geeft aan welke codelijst van toepassing is. In de XSD is dit uitgewerkt door middel van het toevoegen van een verplicht attribuut codespace. De waardes in codespace zijn overgenomen van de Engelse namen van de domeinen, die in de catalogus beschreven staan. Indien er een andere codeSpace naam wordt aangeleverd, is dit geen geldige XML.

Voorbeeld:

IMBRO 6.2

DATE

DATE

Element van het type xml:Date Deze zijn elementen met het domein Datum in de gegevensdefinitie en hebben als conventie een suffix Date. Zij maken gebruik van het standaard xml Date type. • domein Datum : type xml:Date datum volgens de Greogoriaanse kalender, bestaande uit jaar, maand en dag, inclusief de tijdzone, YYYY-MMDD(zzzz). Tijdzone informatie is optioneel.

Voorbeeld:

2015-0405+01:00 6.3

DIS

DIS

Element uitsluitend voor leverancier en bronhouder Dit element wordt uitsluitend uitgegeven aan de leverancier of de bronhouder van het registratieobject. Voor andere data-afnemers wordt dit element niet uitgegeven.

Voorbeeld:

77778888 6.4 ID

ID Element met een verplicht attribuut gml:id Een aantal elementen afkomstig van de GML standaard hebben een verplicht attribuut gml:id. Deze identifier is

Pagina 40 van 50


bedoeld voor gebruik in referenties binnen een XML document. Hij moet uniek zijn binnen de scope van het XML document. In de BRO wordt deze identificatie op geen andere manier gebruikt en wordt daarom ook niet opgeslagen. Bij uitgifte wordt de identificatie gegenereerd op het moment van uitgifte. Eenzelfde element zal op verschillende momenten een ander gml:id krijgen. Voorbeeld:

6.5 MEA

MEA Element van het type gml:Measure Dit element heeft een verplicht attribuut uom om de eenheid aan te geven. Voor de symbolen die bij uom kunnen worden ingevuld volgt de BRO de UCUM standaard. In het UML model en de XSD zijn er subtypes voor een aantal relevante grootheden gedefinieerd, gebaseerd op gml:Measure. Voor elk subtype is de uom gedefinieerd en kan geen andere waarde hebben. Indien er een andere uom wordt aangeleverd, is dit geen geldige XML. Voor numerieke waarden met een domein Rationaal getal met lengte x.x in de gegevensdefinitie gelden de volgende algemene regels m.b.t. het aantal decimalen en het aanvullen met nullen en afkappen van waarden. Indien een waarde 3.1 voor een attribuut met het het domein Rationaal getal 2.2 wordt aangeleverd, wordt dit getal bij uitlevering aangevuld tot 3.10. Tot de maximale precisie van het domein worden er nullen toegevoegd aan het getal. Bij uitgifte wordt dan de waarde 3.10 uitgeleverd. Indien er een waarde met grotere precisie wordt aangeleverd dan gespecificeerd, dan wordt dit getal afgekapt. Het getal 3.288 wordt afgekapt tot 3.28 voor het domein Rationaal getal 2.2. Bij uitgifte wordt dan de waarde 3.28 uitgeleverd.

Voorbeeld:

3.300 6.6 MEA NIL

MEA NIL Element van het type gml:Measure, maar mag leeggelaten worden Dit is een element van het type gml:MeasureType (zie uitwerking ‘MEA’). Bij aanlevering volgens IMBRO moet het element verplicht worden ingevuld. Bij aanlevering volgens

Pagina 41 van 50


IMBRO/A mag het element leeggelaten worden. Het element is verplicht maar kan worden leeg gelaten met xsi:nil="true". Het attribuut uom is verplicht, ook al is de waarde niet aanwezig. Indien het element optioneel is, mag het geheel weggelaten worden, indien er in de werkelijkheid geen waarde aanwezig is (zowel bij IMBRO als IMBRO/A) Voorbeeld:

1.2 Voorbeeld:

6.7 PT

PT Element van het type gml:PointType Coordinaten worden conform NEN3610 specificaties in het element pos uitgewisseld. Het coordinates element wordt niet gebruikt en door de BRO genegeerd. Het element pos heeft een verplicht attribuut srsName waarmee het coordinaatsysteem wordt aangeven van de aangeleverde coordinaten. Geldige uri’s zijn bv. : "urn:ogc:def:crs:EPSG::28992" voor RD , "urn:ogc:def:crs:EPSG::4326" voor WGS84. Het coordinaatsysteem bepaalt wat de coordinaten betekenen. Voor RD worden respectievelijk x en y uitgewisseld in meters, voor ETRS89 worden respectievelijk lat en long uitgewisseld in decimale graden. De volgende tabel geeft aan de mogelijke aanleveringen weer:

Referentiestelsel

urn

type

volgorde

eenheid

RD

urn:ogc:def:crs :EPSG::28992 urn:ogc:def:crs :EPSG::4326 urn:ogc:def:crs :EPSG::4258

cartesisch

x,y

m

geografisch

lat, long (φ,λ) lat, long (φ,λ)

decimale graden decimale graden

WGS84 ETRS89

geografisch

Voorbeeld:

136777.000 455855.000 6.8

TIME

TIME

Element van het type xml:DateTime

Pagina 42 van 50


Deze elementen hebben het domein DatumTijd in de gegevensdefinitie en hebben als conventie een suffix Time. Zij maken gebruik van het standaard xml DateTime type. • domein Datum/Tijd : type xml:DateTime een datum met tijd informatie, YYYY-MMDDThh:mm:ss(.sss)(zzzz). Milliseconden worden niet gebruikt in de BRO. Tijdzone informatie is optioneel. Voorbeeld: 2015-05-26T15:05:23+02:00

6.9 TPT

TPT Element van het type gml:TimePositionType Dit is een type uit GML voor het beschrijven van een positie in de tijd waarin verschillende mogelijkheden gecombineerd zijn volgens de ISO 19108 standaard. Dit type wordt gebruikt voor alle attributen met het domein OnvolledigeDatum bij IMBRO/A. Bij IMBRO is het domein dan Datum of DatumTijd. domein Datum : type xml:Date, een datum zonder tijd informatie, YYYY-MM-DD met optionele tijdzone informatie. Deze elementen hebben de suffix Date als conventie. domein Datum/Tijd : type xml:DateTime, een datum met tijd informatie, YYYY-MM-DDThh:mm:ss(.sss)(zzzz). Milliseconden worden niet gebruikt in de BRO. Tijdzone informatie is optioneel. Deze elementen hebben de suffix Time als conventie. domein OnvolledigeDatum : type xml: CalDate met verschillende mogelijkheden om onvolledige datums uit te wisselen volgens formaten gespecificeerd in de gegevensdefinitie. In dit geval wordt gebruik gemaakt van het attribuut indeterminatePosition en kan de datum leeg gelaten worden. Voorbeeld: ConstructionDate heeft het domein xml:Date bij IMBRO en OnvolledigeDatum bij IMBRO/A. In het geval van een onbekende datum wordt gebruik gemaakt van het attribuut indeterminatePosition en kan de datum leeg gelaten worden (tweede voorbeeld). Ook kan een onvolledige datum (in dit geval YYYY-DD) ingevuld worden (derde voorbeeld).

Voorbeeld:

2015-01-01+01:00 Voorbeeld:

Voorbeeld:

2015-01-01+01:00

Pagina 43 van 50


Bijlages

Bijlage A: Vertaalslag Engels – Nederlands A1: Het registratieobject grondwatermonitoringput Engels GroundwaterMonitoringWell broId deliveryAccountableParty objectIdAccountableParty deliveryResponsibleParty qualityRegime deliveryContext historicalId constructionStandard owner wellHeadProtector maintenanceResponsibleParty geoOhmTester initialFunction constructionDate abandonmentDate DeliveredVerticalPosition localVerticalReferencePoint offset verticalPositionGroundLevel verticalPositioningMethod verticalPositioningOperator verticalDatum RegistrationHistory registrationStatus objectRegistrationTime latestAdditionTime registrationCompletionTime corrected latestCorrectionTime underReview underReviewTime deregistered deregistrationTime reregistered reregistrationTime DeliveredLocation location CRS

Nederlands Grondwatermonitoringput BRO-ID bronhouder object-ID bronhouder dataleverancier kwaliteitsregime kader aanlevering historische naam kwaliteitsnorm inrichting eigenaar beschermconstructie onderhoudende instantie zoutwachter initiële functie datum ingericht datum opgeruimd Aangeleverde verticale positie lokaal verticaal referentiepunt verschuiving verticale positie maaiveld methode verticale positiebepaling uitvoerder verticale positiebepaling verticaal referentievlak Registratiegeschiedenis registratiestatus tijdstip registratie object tijdstip laatste aanvulling tijdstip voltooiing registratie gecorrigeerd tijdstip laatste correctie in onderzoek in onderzoek sinds uit registratie genomen tijdstip uit registratie genomen weer in registratie genomen tijdstip weer in registratie genomen Aangeleverde locatie locatie referentiestelsel

Pagina 44 van 50


horizontalPositioningMethod horizontalPositioningOperator StandardizedLocation location CRS appliedTransformation GeoOhmTester serialNumber inUse ElectrodePair serialNumber measurementVerticalPosition electrodeDistance annularInfillMaterial MonitoringTube tubeNumber type artesianWellCap fullyDescribed inUse status length topVerticalPosition verticalPositioningMethod verticalPositioningOperator Screen material internalDiameter topVerticalPosition bottomVerticalPosition OtherTubePart type material internalDiameter topVerticalPosition bottomVerticalPosition

methode locatiebepaling uitvoerder locatiebepaling Gestandaardiseerde locatie locatie referentiestelsel toegepaste transformatie Zoutwachter volgnummer in gebruik Elektrodenpaar volgnummer meetpositie elektrodeafstand type aanvulling Monitoringbuis buisnummer type drukdop volledig beschreven in gebruik status lengte verticale positie bovenkant methode verticale positiebepaling uitvoerder verticale positiebepaling Filter materiaal interne diameter verticale positie bovenkant verticale positie onderkant Ander buisdeel type materiaal interne diameter verticale positie bovenkant verticale positie onderkant

A2: Domeinen Engels urn:bro:QualityRegime urn:bro:ETRSTransformation urn:bro:HorizontalCRS:EPSG urn:bro:IndicationYesNo urn:bro:IndicationYesNoUnknown urn:bro:gmw:InitialFunction urn:bro:DeliveryContext urn:bro:gmw:ConstructionStandard

Nederlands Kwaliteitsregime ETRSTransformatie HorizontaalReferentiestelsel IndicatieJaNee IndicatieJaNeeOnbekend InitiëleFunctie KaderAanlevering KwaliteitsnormInrichting

Pagina 45 van 50


urn:bro:QualityRegime urn:bro:gmw:LocalVerticalReferencePoint urn:bro:gmw:HorizontalPositioningMethod urn:bro:gmw:VerticalPositioningMethod urn:bro:RegistrationStatus urn:bro:gmw:MonitoringTubeType urn:bro:gmw:TubeStatus urn:bro:gmw:AnnularInfillMaterial urn:bro:gmw:OtherTubePartType urn:bro:gmw:WellHeadProtector urn:bro:gmw:MaterialType urn:bro:gmw:MonitoringTubeType urn:bro:VerticalDatum

Kwaliteitsregime LokaalVerticaalReferentiepunt MethodeLocatiebepaling MethodeVerticalePositiebepaling Registratiestatus Sondeermethode StatusBuis TypeAanvulling TypeAnderBuisdeel TypeBeschermconstructie TypeMateriaal TypeMonitoringbuis VerticaalReferentievlak

Pagina 46 van 50


Bijlage B: Achtergrond bij de techniek rondom het koppelvlak

SOAP Het Simple Object Access Protocol (SOAP) is een protocol voor het versturen van XML berichten. Het doel van SOAP is het uitwisselen van data over netwerken en daarom houdt het zich bezig met het inkapselen en coderen van XML data en het definiëren van regels voor het versturen en ontvangen van die data. Een SOAP bericht, dus een ingekapseld en gecodeerd XML document, wordt getransporteerd via HTTP van het ene (koppelvlak van een) systeem naar het andere. Deze SOAP berichten zijn niet bedoeld voor menselijke interpretatie, maar worden door het ontvangende systeem verwerkt. Elk SOAP bericht bestaat uit drie elementen, namelijk de “Envelope”, de “Header” en de “Body”.

Figuur 11: Structuur van een SOAP bericht

WSDL Bij elk koppelvlak dat is gerealiseerd door middel van een W3C webservice hoort een WSDL (Web Service Definition Language) document. Dit XML document beschrijft in technische termen welke transacties er mogelijk zijn via de webservice. Onder andere staat gedefinieerd hoe men toegang kan krijgen tot de service en welke gegevens moeten worden ingevoerd en welk bericht als respons verwacht kan worden van het systeem.

Pagina 47 van 50


Figuur 12: Structuur van een WSDL document1

1

Geinspireerd door:

http://download.oracle.com/otn_hosted_doc/jdeveloper/1012/web_services/ws_wsdlstru cture.html http://www.herongyang.com/WSDL/WSDL-11-Introduction-What-Is-WSDL-11.html http://predic8.com/wsdl-reading.htm

Pagina 48 van 50


Synchrone versus asynchrone webservices Er bestaan synchrone en asynchrone webservices. De kenmerken van beide zijn hieronder verder uitgewerkt: • Synchrone webservice: Bij een synchrone webservice wacht het systeem dat het verzoek heeft verstuurd tot er een antwoord ontvangen is. Wanneer een verzoek enige verwerkingstijd vergt bij het ontvangende systeem (in dit geval het systeem van de BRO), blijven de resources bij de aanvrager voor dit verzoek in gebruik en kan er dus maar een beperkt aantal transacties tegelijk worden verwerkt. Het gevolg kan zijn dat een gebruiker geen transacties kan starten en moet wachten tot er resources zijn vrijgekomen. • Asynchrone webservice: Bij een asynchrone webservice verstuurt het systeem van de data leverancier / afnemer een verzoek en plaatst deze in de wachtrij van het andere systeem (het systeem van de BRO). Het antwoord dat hierop volgt is enkel een ontvangstbevestiging van het verzoek en niet zozeer het antwoord op het verzoek. Wanneer het verzoek vooraan in de wachtrij is aangekomen en zodoende verwerkt wordt door het systeem van de BRO, volgt het daadwerkelijke resultaat als antwoord op het verzoek, later in de tijd. Het systeem van de BRO stuurt een verzoek met daarin een SOAP bericht met het resultaat van de transactie naar het aanvragende systeem. Het systeem van de aanvrager stuurt vervolgens een ontvangstbevestiging. Bij deze aanpak worden dus meerdere request-response paren verstuurd, worden resources dus direct weer vrijgegeven en kan een gebruiker zijn transactie altijd starten. De keuze voor een synchrone of asynchrone webservice hangt sterk af van de situatie. Een synchrone webservice is eenvoudiger, maar gaat minder efficiënt om met de beschikbare resources. Asynchrone webservices zijn efficiënter, maar daarbij wel complexer. Hoewel deze complexiteit grotendeels kan worden opgevangen door moderne servers, zijn er situaties waarin toch de keuze voor een synchrone webservice wordt gemaakt, bijvoorbeeld wanneer er sprake is van een interactief proces waarbij de gebruiker pas verder kan als het resultaat van de webservice bekend is.

Pagina 49 van 50


Figuur 13: Synchrone webservice

Figuur 14: Asynchrone webservice

Pagina 50 van 50

Basisregistratie Ondergrond (BRO) Koppelvlakbeschrijving

Recommend Documents