Aanleveren software

Op de speciale pagina voor Softwareontwikkelaars vind je veel tips. Verder staat in de BRO Productomgeving staat de Handreiking aanleveren BRO-gegevens.

Data in de BRO vallen in de categorie geo-informatie en daarvoor is een NEN3610- conform format ontwikkeld, genaamd IMBRO/XML. Per datatype wordt de exacte inhoud hiervan in het dataproject bepaald. Een gebruiker dient zelf zorg te dragen voor de vertaling van het NEN3610-conforme format naar zijn eigen systeemomgeving.
Naast IMBRO is er ook IMBRO/A, dat een beperktere set attributen bevat. IMBRO/A is van toepassing op reeds bestaande gegevens, waarvan niet alle BRO-vereiste attributen voorhanden zijn.

Meer informatie over het aanleveren van gegevens is te vinden in de Handreiking aanleveren BRO-gegevens.

U kunt in de BRO Productomgeving diverse voorbeeldbestanden bekijken. Je kunt het aanleveren van gegevens testen in de demo-omgeving van het Bronhouderportaal, zodat je kunt zien hoe het Bronhouderportaal werkt.  Heb je geen toegang tot de demo-omgeving, neem dan contact op met de BRO Servicedesk.

De BRO moet, net als alle basisregistraties, voldoen aan door de overheid opgestelde regels, zoals:  werken onder architectuur en zoveel mogelijk houden aan geldende nationale en internationale standaarden. In de architectuur BRO hebben wij vastgelegd welke standaarden gebruikt moeten worden binnen de systemen van de BRO.

Voor de communicatie via webservices kan dit als volgt worden samengevat: de basisregistratie is ontworpen als een informatiesysteem dat via webservices communiceert met andere systemen (machine to machine).  Voor de uitwisseling van gegevens via deze webservices is gesteld dat dit moet voldoen aan de internationale standaarden: OGC en W3C. Dit maakt dat we, net als de andere basisregistraties, gebruik moeten maken van XML-formaten. Deze worden nu nog hoofdzakelijk aangeboden via een SOAP-protocol. Sinds kort worden de webservices ook steeds vaker via het Rest-protocol aangeboden. Dat gebeurt nog vooral in het XML-formaat maar ook al deels in JSON. In de toekomst zal de BRO meer en meer  gebruik gaan maken van JSON als formaat.

Om jouw software aan te passen om het juiste BRO-verzoek te laten genereren, zijn technische XML schema definities (XSD’s) beschikbaar: https://schema.broservices.nl/xsd/. Je vindt daar generieke BRO schema’s (brocommon) en specifieke schema’s. Handig om te weten is dat 'is' staat voor innameservice en 'ds' staat voor dispatch ofwel de uitgifteservice.

Wil je meer weten? Bekijk alle instructies die inmiddels beschikbaar zijn en lees daar meer over de mogelijkheden.

In de Handreiking BRO-gegevens aanleveren (hoofdstuk 7) vind je enkele specifieke, kleine stukjes code uit XML-bestanden van een BRO-verzoek. Dat kan praktisch zijn voor softwareleveranciers en anderen die gegevens willen aanleveren en op zoek zijn naar extra uitleg van de opbouw van een BRO-verzoek. Bekijk dat en ontdek meer in de praktische handreiking voor BRO-gebruikers; een algemene introductie voor het opstellen van XML-bestanden voor de BRO.

In de catalogus van elk registratieobject staan waardenlijsten met de toegelaten waarden van bepaalde attributen. Het is mogelijk om een lijst met alle waarden op te vragen bij de LV BRO via een REST-service. Er zijn verschillende opties. Je kunt bijvoorbeeld alle waardelijsten opvragen voor een registratieobject. Maar ook kun je de inhoud van waardelijsten opvragen. Als resultaat ontvang je dan een JSON-bericht met daarin alle waarden van een bepaalde waardelijst met de beschrijvingen. Volg daarvoor de instructie van de REST-service. Die instructie bevat de beschrijving van de interface van de waardelijst service (Engels: "reference code service" of kortweg "refcode service").

Bij sommige objecten worden alle beschikbare gegevens altijd in 1x geregistreerd. De registratie van gegevens over zo'n object is dan een eenmalige gebeurtenis en hebben geen levensloop. Andere objecten kennen een levensloop met een begin en een eind. In de tussenliggende periode kunnen gebeurtenissen optreden, die geregistreerd moeten worden in de LV-BRO. Een registratieobject met levensloop is bijvoorbeeld Bodemkundig booronderzoek (BHR-P) en Grondwaterstandonderzoek (GLD) en zonder is bijvoorbeeld Geotechnisch Sondeeronderzoek (CPT) en Grondwatersamenstellingsonderzoek (GAR). Meer uitleg hierover vind je in de praktische Handreiking BRO-gegevens aanleveren (paragraaf 3.1).

Bij materiële geschiedenis gaat het om een verandering in de werkelijkheid, waardoor bestaande gegevens een andere waarde krijgen of bestaande gegevens niet langer van belang zijn of dat er nieuwe gegevens ontstaan. Bij formele geschiedenis gaat het om corrigeren van een geregistreerd gegeven, omdat er een fout is gemaakt. Meer uitleg vind je in de een van de gegevenscatalogi of de praktische Handreiking BRO-gegevens aanleveren (paragraaf 3.4).

Bij aanvullingen worden nieuwe gegevens toegevoegd aan het in de LV-BRO geregistreerde object. De aangeboden gegevens zijn niet al aanwezig in de registratie. Bij aanvullingen worden nieuwe waarden voor reeds in de LV-BRO geregistreerde gegevens gemeld. Hierbij moet ieder tweetal van opeenvolgende waarden verschillend zijn.
Bij correcties gaat het om het corrigeren van een geregistreerd gegeven, omdat er een fout is gemaakt. Meer uitleg vind je in de praktische Handreiking BRO-gegevens aanleveren (paragraaf 3.4.1 bij 'Materiële geschiedenis').

Lever je gegevens aan de BRO voor een registratieobject waarbij een van de aan te leveren attributen het tijdstip is, zoals bijvoorbeeld bij grondwaterstandsonderzoek (GLD), dan is het belangrijk dat jouw softwareleverancier de ISO 8601 standaard goed toepast. De meeste computertalen doen dit automatisch goed. Ben je betrokken bij softwareontwikkeling voor de BRO, lees dan meer over het afhandelen van tijdstippen op de BRO Productomgeving.

Het KvK-nummer staat bij jouw ontvangen machtiging (achter de naam van de bronhouder) in het Bronhouderportaal. Zo hoef je het KvK-nummer van de bronhouder niet ergens anders op te zoeken en weet je zeker dat je het juiste nummer gebruikt.  Een complete lijst van de bronhouders met KvK-nummers vind je op de pagina Aangemeld bij de BRO.

Voordat je  jouw bestand met gegevens aanbiedt in het Bronhouderportaal is het handig om het XML-formaat te testen. Speciaal daarvoor is er een (REST)validatieservice in het Bronhouderportaal beschikbaar. Ook in de demo-omgeving van het Bronhouderportaal is er een validatieservice. Heb je nog geen demo-account van het Bronhouderportaal? Mail de Servicedesk.

Je kunt volledig geautomatiseerd BRO-gegevens opvragen via een SOAP webservice. Je vindt de instructie hiervoor op de site van Basisregistratie Ondergrond. Nadat je bent aangesloten op de SOAP webservices is de overgang van de demo-omgeving naar de productieomgeving niet meer dan het aanpassen van het endpoint voor de productieomgeving en het vervangen van het testcertificaat door uw eigen geldig certificaat. Als het endpoint is aangepast, is de aansluiting op de SOAP webservice voor dit registratieobject gerealiseerd.

In de Handreiking voor afname BRO-gegevens staat hoe de url van een endpoint is opgebouwd. Met die uitleg is het mogelijk om alle endpoints af te leiden.

Voor de BRO nemen softwareleveranciers een belangrijke rol in. Zij faciliteren bronhouders bij het voorbereiden en aanleveren van gegevens aan de BRO en helpen gebruikers om data in de gewenste set op te vragen. Elke twee weken is er op donderdagochtend een online Softwareplein. Verder kun je natuurlijk contact opnemen met de Servicedesk en de vragen/antwoorden van het Softwareplein raadplegen bij de BRO Productomgeving.