Uitgiftehandboek CPT

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 geotechnisch sondeeronderzoek.
Het uitgiftehandboek richt zich op de partijen die geotechnisch sondeeronderzoek 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,

• 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.

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 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.

1.4. Versiehistorie

1.5. Contactinformatie

Voor vragen, suggesties of opmerkingen over de inhoud van dit document kunt u contact opnemen met de BRO Servicedesk. Bel 088 – 8644 999 of mail naar support@broservicedesk.nl.

 Verder vindt u op basisregistratieondergrond.nl verdere technisch inhoudelijke instructie voor het aanleveren van gegevens aan de landelijke voorziening BRO.

2. Uitgifte van gegevens

2.1. 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 ander aspect is dat men de gegevens altijd in het IMBRO-XML formaat krijgt.

2.1.1. Communicatie tussen twee systemen

De data-afnemer die voor het opvragen van gegevens van geotechnisch sondeeronderzoek gebruikmaakt 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 geotechnisch sondeeronderzoek 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.

2.1.2. Opties bij opvragen via de webservice

De uitgiftewebservice voorziet in elementaire functionaliteit en die dekt twee 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 dan kan hij per object alle gegevens opvragen.
De twee opties zijn vertaald in twee verzoeken:

1. Een verzoek tot verzending van de kengegevens van een aantal geotechnisch sondeeronderzoeken.

De data-afnemer geeft in zijn verzoek de verzameling kenmerken mee waaraan het geotechnisch sondeeronderzoek dat hij zoekt moet 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 bepaald geotechnisch sondeeronderzoek.

De data-afnemer geeft in zijn verzoek het BRO-ID van het geotechnisch sondeeronderzoek dat hij wil hebben mee. In antwoord daarop krijgt hij alle gegevens van het object geleverd.
In de volgende paragrafen wordt de verwerking in meer detail beschreven.

2.1.3. 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 het geotechnisch sondeeronderzoek 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 geotechnisch sondeeronderzoeken die aan de meegegeven kenmerken voldoen.

   • Wanneer de verzameling gegevens te groot ( > 2.000) is, 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.

2.1.4. Opvragen van gegevens

Het opvragen van de gegevens van een geotechnisch sondeeronderzoek verloopt iets anders dan het opvragen van kengegevens. Het verschil met het opvragen van kengegevens is dat er in de vierde stap geen controle op volume hoeft te worden uitgevoerd, aangezien er maar van één geotechnisch sondeeronderzoek gegevens worden opgevraagd.

3. Opvragen via de webservice: de berichten

3.1. Opvragen van kengegevens

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

3.1.1. Verzoek tot verzending

3.1.2. Bericht van afwijzing

3.1.3. Bericht van verzending

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.

3.2. Opvragen van gegevens

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

3.2.1. Verzoek tot verzending

3.2.2. Bericht van afwijzing

3.2.3. Bericht van verzending

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:

3.3. 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 als de stroomtoevoer hapert.

4. Specificatie van de berichten bij gebruik van de webservice

4.1. Inleiding

In dit hoofdstuk worden de gegevens beschreven 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.
De berichten worden 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 alleen gedefinieerd als het niet in de catalogus is opgenomen of wanneer er bijzondere regels gelden. Als alleen de kardinaliteit van een gegeven afwijkt van die in de catalogus, is dat geen reden geweest het hier op te nemen. Delen van de definitie van een gegeven die ongewijzigd zijn ten opzichte van de catalogus zijn grijs gemaakt. Nieuwe gegevens die voorkomen bij meerdere berichten worden eenmalig gedefinieerd. In lijn daarmee worden aan het eind van het hoofdstuk de domeinen behandeld die specifiek zijn voor de berichten.

4.2. Berichten

4.2.1. Verzoek tot verzending kengegevens

4.2.2. Verzoek tot verzending gegevens

4.2.3. Bericht van afwijzing

4.2.4. Bericht van verzending kengegevens

tijdstip van uitgifte
Naam attribuut	tijdstip van uitgifte
Definitie	De datum en het tijdstip waarop het bericht door de BRO is verstuurd.
Kardinaliteit	1
Domein	DatumTijd
uitgiftedocumenttype
Naam attribuut	uitgiftedocumenttype
Definitie	De aanduiding van het type document dat de afnemer wordt toegezonden in antwoord op zijn verzoek.
Kardinaliteit	0..2
Domein	Uitgiftedocumenttype
Type	Codelijst
aantal documenten
Naam attribuut	aantal documenten
Definitie	Het aantal uitgiftedocumenten dat in het bericht zit.
Kardinaliteit	1
Domein	Aantal
Maximale lengte	4
Waardebereik	0 tot 2.000

4.2.5. Bericht van verzending gegevens

4.3. Specifieke domeinen voor uitgifte

4.3.1. 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

4.3.2. 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).

4.3.3. 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.

4.3.4. 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.

4.3.5. 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.

4.3.6. RedenAfwijzing

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

4.3.7. Uitgiftedocumenttype

4.4. Uitgiftedocumenten

4.4.1. CPT-C

4.4.2. CPT-O

4.4.3. CPT-O-DP

Het verschil met CPT-O is dat CPT-O-DP de volgende gegevens bevat:

4.4.4. BRO-DO