Basisregistratie Ondergrond (BRO) Handleiding voor aansluiten op webservices. Datum 13 januari 2017 Status Versie 1.0

Transcriptie

1 Basisregistratie Ondergrond (BRO) Handleiding voor aansluiten op webservices Datum 13 januari 2017 Status Versie 1.0

2

3 Inhoudsopgave Inleiding... 5 Doelgroep... 5 Leeswijzer... 5 Zelfstandig aan de slag... 6 Praktische informatie over aansluiten op de webservices van de BRO... 7 Inleiding... 7 Algemene eisen... 7 Aansluiten per registratieobject... 7 Documentatie voor aansluiten... 7 De vier stappen van het aansluiten... 9 Pilot- en ketentestomgeving, inregelomgeving en productieomgeving... 9 Beoogd resultaat Doorlooptijd Stap 1: Toegang Inleiding Middelen Uitleg en acties Resultaat Stap 2: Realisatie Inleiding Middelen Uitleg en acties Resultaat Stap 3: Aansluittoets Inleiding Middelen Uitleg en acties Resultaat... 22

4 Stap 4: Definitieve aansluiting Inleiding Middelen Uitleg en acties Resultaat Pagina 4 van 24

5 Inleiding In de Basisregistratie Ondergrond (BRO) worden gegevens over de ondergrond, modellen, infrastructuur en vergunningen opgeslagen. De BRO wordt gefaseerd per registratieobject opgebouwd. Dat betekent ook dat gefaseerd aangesloten kan worden. Deze handleiding beschrijft hoe dataleveranciers en data-afnemers voor een specifiek registratieobject kunnen aansluiten op de webservices van de BRO. Doelgroep Deze handleiding is gericht op: Partijen die gegevens willen aanleveren aan de BRO, de dataleveranciers Partijen die gegevens willen opvragen bij de BRO, de data-afnemers Voor zowel softwareontwikkelaars als andere betrokken medewerkers van de organisaties die willen aansluiten, bevat deze handleiding informatie. Leeswijzer Allereerst wordt in het volgende hoofdstuk een introductie met praktische informatie over het aansluiten gegeven. Er wordt met name ingegaan op technische achtergrondinformatie, de ondersteunende documentatie en er wordt een schematisch overzicht gegeven van de vier stappen van het aansluiten op de webservices. Deze stappen komen vervolgens elk in een afzonderlijk hoofdstuk aan bod: stap 1 toegang, stap 2 realisatie, stap 3 aansluittoets en tot slot stap 4 aansluiten. Neemt u deel aan een pilot of ketentest? Dan zijn alleen stap 1 en 2 van deze handleiding van toepassing. Tot slot hoort bij de handleiding een inlegvel. Op het inlegvel staan voor één registratieobject alle links naar de bijbehorende documentatie, formulieren en webservices. Ook voor de pilot of ketentest is er per registratieobject een eigen inlegvel. Daar waar van toepassing, verwijst deze handleiding naar dat inlegvel.! Let op! Aandachtspunten worden telkens in een kader aangegeven. Pagina 5 van 24

6 Zelfstandig aan de slag Deze handleiding is erop gericht dat dataleveranciers en dataafnemers zelfstandig aan de slag kunnen om aan te sluiten op de BRO voor een specifiek registratieobject. Mochten er toch problemen of vragen zijn, dan kan op werkdagen tussen 9.00 en uur contact opgenomen worden met de BRO Servicedesk. Telefoonnummer: ! Het gebruik van de Selfservicedesk is echter sneller: U kunt daar gebruik van maken zodra uw organisatie is aangemeld bij de BRO (zie stap 1). De Selfservicedesk is echter niet toegankelijk met een smartphone of tablet. Algemene informatie over de BRO is te vinden op: of Pagina 6 van 24

7 Praktische informatie over aansluiten op de webservices van de BRO Inleiding Dit hoofdstuk geeft praktische informatie over het aansluiten op de webservices. Algemene eisen Allereerst is er een aantal vereisten waar een dataleverancier en data-afnemer aan moet voldoen om aan te kunnen sluiten op de BRO: Kennis van het registratieobject dat men wil registreren en/of opvragen en de daarbij behorende data. IT-kennis: programmeerervaring (Java, Microsoft.NET C#) of ervaring in het gebruik van webservices (met name Soap services, XML, UML) om de koppeling te realiseren. Aansluiten per registratieobject Het aansluiten op de BRO verloopt per registratieobject. Voor elk registratieobject worden namelijk afzonderlijke webservices ontwikkeld om geautomatiseerd gegevens uit te kunnen wisselen met de BRO. Hierbij maakt de BRO als basisregistratie zo veel mogelijk gebruik van de standaarden van de eoverheid, zoals Digikoppeling, Digimelding en Digilevering. Voor de geautomatiseerde uitwisseling van gegevens heeft de BRO, conform de Digikoppeling specificaties, Soap webservices gerealiseerd die beveiligd zijn met een PKIoverheid services server certificaat. Dataleveranciers en data-afnemers kunnen aansluiten op de BRO door hun eigen software te koppelen aan deze webservices. Dit is een traject waarbij zowel organisatorische, inhoudelijke en technische aspecten een rol spelen. De BRO biedt documentatie aan om dit proces te ondersteunen. Documentatie voor aansluiten Voor de realisatie van de software zijn voor een registratieobject deze documenten nodig (zie inlegvel, punt A): Formele documenten Extra documenten(en) Voorbeeldclients met toelichtend document Pagina 7 van 24

8 Het is handig om te weten wat in de formele documenten van een registratieobject staat: catalogus, de handboeken voor inname of uitgifte en de koppelvlakbeschrijvingen. Daarom volgt hieronder een nadere toelichting. Allereerst staan in de catalogus de definities van alle entiteiten en attributen van een specifiek 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 van een specifiek registratieobject. Alle registratieobjecten kunnen aangeboden worden via webservices; bepaalde registratieobjecten kunnen ook aangeboden worden via het innameloket. Bij uitgifte is dat anders. Daar kan de afnemer voor alle objecten kiezen tussen uitgifte van gegevens via 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 van het betreffende registratieobject nodig. De koppelvlakbeschrijvingen van een specifiek registratieobject zijn geschreven voor softwareontwikkelaars en zijn bedoeld voor de partijen die de webservices gaan gebruiken. Op basis van de twee vorige type 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. Ook worden in de koppelvlakbeschrijving voorbeeldberichten gegeven en foutmeldingen toegelicht. De koppelvlakbeschrijving gaat dus in op de technische kant van de overdracht van gegevens van dat registratieobject. In de volgende afbeelding is schematisch weergegeven hoe deze formele documenten met elkaar samenhangen. Pagina 8 van 24

9 Dataleveranciers Data-afnemers Gegevensdefinitie registratieobject Catalogus voor registratieobject Beschrijving transacties Innamehandboek Uitgiftehandboek Beschrijving technische realisatie Koppelvlakbeschrijving innamewebservice Koppelvlakbeschrijving uitgiftewebservice Bij stap 2 Realisatie wordt deze samenhang nog kort toegelicht, zodat duidelijk is welk document waarvoor nodig is bij de realisatie van de software. Daar wordt ook specifiek ingegaan op het gebruik van het extra bestand en de voorbeeldclients. De vier stappen van het aansluiten Het aansluiten op de BRO bestaat uit vier stappen: het regelen van toegang (1), de realisatie van software (2), de aansluittoets van de software (3) en tot slot het aansluiten (4). In deze handleiding wordt beschreven wat bij elke stap gedaan moet worden. Neemt u deel aan de pilot of ketentest, dan hoeft u alleen stap 1 en 2 te doorlopen. Zo is de eerste stap het administratieve gedeelte om toegang te krijgen. Dit bestaat uit het aanmelden, het aanvragen van rechten en de authenticatie. De tweede stap is het technische gedeelte: de realisatie van de software om met de BRO te communiceren. Bij de realisatie van de software is het mogelijk om (onderdelen van) de voorbeeldclients van TNO te gebruiken, waarin kleine aanpassingen gedaan moeten worden, of alles zelf te bouwen. De derde stap is de aansluittoets waarbij de dataleverancier en data-afnemer kijken of het systeem werkt ofwel de proef van bekwaamheid. Zodra dat gelukt is, kunt u officieel aansluiten. Pilot- en ketentestomgeving, inregelomgeving en productieomgeving De pilot en ketentest vinden plaats in de pilot- en ketentestomgeving. Als de BRO voor dat registratieobject alle ontwikkelfases heeft doorlopen, gaat dat gedeelte van de BRO live. Vanaf dat moment vindt het aansluiten op de BRO plaats in de inregel- en productieomgeving. De eerste drie stappen Pagina 9 van 24

10 worden dan doorlopen in de inregelomgeving. Zodra de aansluittoets succesvol is afgerond krijgt men toegang tot de productieomgeving voor de definitieve aansluiting. Deze definitieve aansluiting is de laatste stap, stap 4. Vanuit de pilot- en ketentestomgeving is het nooit mogelijk om over te gaan naar de productieomgeving. In de volgende afbeelding zijn de stappen van het aansluiten en de verschillende omgevingen schematisch weergegeven. Start 1 Dataleverancier/ data-afnemer Stap 1: Toegang Basisregistratie Ondergrond (BRO) 2 Stap 2: Realisatie 3 1. Registreren Stap Stap 3: Aansluittoets 3: Test Pilot/ Ketentest Inregel Omgeving 4 Stap 4: Definitieve aansluiting Productie omgeving Einde Systeem van de dataleverancier/ data-afnemer Systeem van de BRO Elke stap wordt uitgebreid beschreven en toegelicht in de volgende hoofdstukken. Fragmenten van de afbeelding komen daarbij terug om aan te geven waar men in het proces zit. Verder is elk hoofdstuk - ofwel elke stap - als volgt opgebouwd: Paragraaf Inleiding Middelen Beschrijving Deze paragraaf beschrijft wat het doel van de stap is en vat kort samen wat de stap inhoudt. Deze paragraaf beschrijft wat nodig is om deze stap uit te voeren. Soms kunnen dat ook middelen zijn die vanuit de BRO geleverd Pagina 10 van 24

11 Uitleg en acties Resultaat worden. Deze paragraaf beschrijft wat gedaan moet worden om de stap uit te voeren. Daar waar afhankelijkheden bestaan, staan de acties in de juiste chronologische volgorde. Deze paragraaf beschrijft wat het resultaat is, als deze stap goed is doorlopen. Beoogd resultaat Het uiteindelijke doel is dat het systeem van een dataleverancier en data-afnemer automatisch gegevens kan aanbieden of opvragen bij de BRO. Doorlooptijd De doorlooptijd van het aansluiten is afhankelijk van de volgende factoren: De timing van de face-to-face audit voor een PKIoverheid services server test- en productiecertificaat (zie stap 1). De beschikbare IT-capaciteit van de dataleverancier en data-afnemer. De mogelijkheid om applicaties en systemen van de dataleverancier en data-afnemer aan te passen. Pagina 11 van 24

12 Stap 1: Toegang Start 1 Dataleverancier/ data-afnemer Stap 1: Toegang Basisregistratie Ondergrond (BRO) 2 Stap 2: Realisatie 3 1. Registreren Stap Stap 3: Aansluittoets 3: Test Pilot/ Ketentest Inregel omgeving Inregel Omgeving 4 Stap 4: Definitieve aansluiting Productie omgeving Einde Systeem van de dataleverancier/ data-afnemer Systeem van de BRO Inleiding De eerste stap is het administratieve gedeelte: het regelen van de toegang. Dit bestaat uit het aanmelden, het aanvragen van rechten en de authenticatie. Zodra de rechten verleend worden, verstrekt de BRO een gebruikersnaam/wachtwoord combinatie. Voor de authenticatie wordt namelijk gebruikgemaakt van een PKIoverheid services server test- en productiecertificaat. Zolang de aanvraag van het PKIoverheid services server test- en productiecertificaat loopt, kan met de gebruikersnaam/wachtwoord combinatie alvast verder gegaan worden met stap 2. Middelen Naast de algemene eisen die in het hoofdstuk met algemene informatie zijn genoemd, zijn voor stap 1 geen aanvullende middelen nodig. Pagina 12 van 24

13 Uitleg en acties 1.1 Aanmelden en rechten aanvragen Niet iedereen heeft toegang tot alle webservices van de BRO. Daarom moeten dataleveranciers en data-afnemers zich eerst aanmelden bij de BRO en vervolgens rechten aanvragen. Het kan daarbij gaan om het recht om (al dan niet via een volmacht van de bronhouder) geautomatiseerd gegevens aan te leveren, het recht om gegevens op te vragen of beide. Dit recht geldt steeds voor één van de registratieobjecten. Deze rechten voor de pilot- en ketentestomgeving of inregelomgeving worden afgegeven voor beperkte tijd en kunnen eventueel verlengd worden. Op het inlegvel staat aangegeven hoe dataleveranciers en dataafnemers zich kunnen aanmelden en rechten kunnen aanvragen (zie inlegvel, punt B).! Als een dataleverancier namens een bronhouder gegevens wil aanleveren, dan moet de bronhouder ook aangemeld zijn bij de BRO. Daarnaast moet bij de BRO bekend zijn dat de dataleverancier namens de bronhouder gemachtigd is om gegevens aan te leveren. Alleen dan heeft een dataleverancier toegang tot de BRO. Dit is van toepassing zodra de Algemene Maatregel van Bestuur van kracht wordt, naar verwachting 1 juli Tot die tijd is het ministerie van Infrastructuur en Milieu tijdelijk de bronhouder. Vanaf 1 juli zult u dus uw rechten moeten wijzigen. 1.2 Gebruikersnaam/wachtwoord combinatie Zodra de aanmelding is voltooid en de rechten zijn verleend, ontvangt de aanvrager ook een gebruikersnaam/wachtwoord combinatie van de BRO. Met deze gebruikersnaam/wachtwoord combinatie kan alvast gestart worden met het technische gedeelte van stap 2, de realisatie. Ondertussen kan de procedure voor de aanvraag van het PKIoverheid services server test- en productiecertificaat doorlopen worden (zie stap 1.3). Het PKIoverheid services server testcertificaat is optioneel voor stap 2, maar een vereiste voor de aansluittoets van stap 3. Het PKIoverheid services server productiecertificaat is vereist voor stap 4.! Is de aanmelding voltooid? Ga dan door met het aanvragen van het PKIoverheid services server test- en productiecertificaat. Deze aanvraagprocedure kan namelijk enige tijd in beslag nemen. Pagina 13 van 24

14 1.3 Aanvragen PKIoverheid services server test- en productiecertificaat voor authenticatie Als authenticatie voor de geautomatiseerde communicatie tussen het softwaresysteem van de dataleverancier of dataafnemer en de BRO worden een PKIoverheid services server test- en productiecertificaat gebruikt. Het zijn de digitale sleutels, die voldoet aan de eisen van de PKIoverheid. Daarbij geeft het PKIoverheid services server testcertificaat toegang tot de inregelomgeving van de BRO. Het PKIoverheid services server productiecertificaat geeft toegang tot de productieomgeving van de BRO. Voor de pilot- en ketentestomgeving is een PKIoverheid services server testcertificaat niet verplicht. Op de website van Logius staat bij welke certificatiedienstverleners de twee PKIoverheid services server certificaten aangevraagd kunnen worden ( Let hierbij op dat het gaat om zowel een PKIoverheid services server test- als een productiecertificaat.! Een PKIoverheid services server testcertificaat is alleen verkrijgbaar bij QuoVadis. De ervaring leert dat het aanvragen van een PKIoverheid services server test- en productiecertificaat tijd kost. Dat heeft verschillende redenen. Allereerst kost het verzamelen van alle informatie om de formulieren in te vullen tijd. Daarnaast is de persoonsidentificatie met een face-to-face audit op kantoor bij de dataleverancier/data-afnemer of bij de certificaatautoriteit onderdeel van de aanvraag. Alle betrokken moeten hierbij aanwezig zijn. Vandaar dat aangeraden wordt om na het aanvragen van de rechten bij de BRO, gelijk door te gaan met het aanvragen van een PKIoverheid services server test- en productiecertificaat bij een certificaatautoriteit. Zodra de aanvraag voor het PKIoverheid services server test- en productiecertificaat is ingediend, kunnen de softwareontwikkelaars starten met stap 2. In afwachting van het PKIoverheid services server testcertificaat geeft de gebruikersnaam/wachtwoord combinatie alvast toegang tot de pilot- en ketentestomgeving of de inregelomgeving. Resultaat Na het uitvoeren van de acties van stap 1 is de toegang tot de BRO geregeld. De dataleverancier en data-afnemer hebben bovendien bij de aanvraag van de rechten een gebruikersnaam/wachtwoord combinatie toegestuurd gekregen. Kortom, het resultaat van deze stap geeft toegang tot de piloten ketentestomgeving of de inregelomgeving. Pagina 14 van 24

15 Stap 2: Realisatie Start 1 Dataleverancier/ data-afnemer Stap 1: Toegang Basisregistratie Ondergrond (BRO) 2 Stap 2: Realisatie 3 1. Registreren Stap Stap 3: Aansluittoets 3: Test Pilot/ Ketentest Inregel Omgeving 4 Stap 4: Definitieve aansluiting Productie omgeving Einde Systeem van de dataleverancier/ data-afnemer Systeem van de BRO Inleiding Nadat in stap 1 de toegang is geregeld, volgt de realisatie van de software. Nu komt het erop aan om het systeem van de dataleverancier en data-afnemer te laten praten met de webservices van de BRO. Hier start dus het technische gedeelte, waarbij het gaat om drie acties. Allereerst moet getest worden of er verbinding gemaakt kan worden met het BRO-systeem. Zodra de verbinding tot stand is gekomen, kan de applicatie gebouwd worden om automatisch gegevens uit te kunnen wisselen met de webservices van de BRO. Dit bestaat uit twee delen: het genereren van de objectclasses en het bouwen van de clients. Hierbij kan gebruikgemaakt worden van de voorbeeldclients of de objectclasses en/of de clients kunnen zelf ontwikkeld worden. Deze tweede stap vindt plaats in de inregelomgeving. In de inregelomgeving kan de client software uitgeprobeerd worden. Voor de pilot en ketentest vindt deze tweede stap plaats in de pilot- en ketentestomgeving. Pagina 15 van 24

16 Middelen Voor het uitvoeren van deze stap zijn de volgende middelen nodig: PKIoverheid services server testcertificaat of gebruikersnaam/wachtwoord combinatie met rechten De documentatie van het betreffende registratieobject (zie inlegvel, punt A). De url van de webservices (zie inlegvel, punt C). Uitleg en acties 2.1 Toegang tot webservices regelen Op basis van de rechten kan toegang verkregen worden tot één of meerdere webservices van de pilot- en ketentestomgeving of inregelomgeving. De url van deze webservices staan vermeld op het inlegvel van het betreffende registratieobject (zie inlegvel, punt C). De interfacebeschrijving van deze webservices is vastgelegd in WSDL bestanden (Web Service Definition Language) met de daaraan gekoppelde XSD bestanden (XML Schema Definitions). Hoe deze files zijn op te vragen via de webservices wordt op het inlegvel beschreven. Eerst zal gekeken moeten worden of verbinding gemaakt kan worden met de webservices en daarna volgt de rest.! Tot de Algemene Maatregel van Bestuur van kracht wordt, naar verwachting 1 juli 2017, is het ministerie van Infrastructuur en Milieu tijdelijk de bronhouder. Dat betekent dat in het Soap-bericht bij delivery accountable party niet alleen de naam maar ook het KvK-nummer van het Ministerie van Infrastructuur en Milieu ingevuld worden, te weten Vanaf 1 juli zult u dit dus moeten veranderen in de software. In dat Soap-bericht moet de naam en KvK-houder van de bronhouder worden ingevuld. 2.2 Testen verbinding en aanbieden van voorbeeldberichten De daadwerkelijke realisatie van de software begint met het testen van de verbinding om te kijken of het lukt om contact te krijgen met de webservices van de BRO. Het testen van de verbinding wordt uitgevoerd met SoapUI. SoapUI is een Javaapplicatie. Voor zowel Linux als Windows en OS X zijn opensource installaties beschikbaar op In het extra bestand Testen verbinding webservices met SoapUI (zie inlegvel, punt A) staat beschreven hoe met SoapUI de verbinding getest kan worden. Vervolgens kan gekeken worden of het aanbieden van voorbeeldberichten werkt. Deze Pagina 16 van 24

17 voorbeeldberichten (registratieverzoek en correctieverzoek) staan in de koppelvlakbeschrijvingen. Tot slot is het uiteraard ook mogelijk om geen gebruik te maken van SoapUI en zelf uit te zoeken hoe de verbinding getest kan worden. 2.3 Kiezen van programmeeromgeving Na het testen van de verbinding moeten de softwareontwikkelaars in de programmeeromgeving van de dataleveranciers of data-afnemers aan de slag om de applicatie te bouwen om aan te kunnen sluiten op de webservices van de BRO. Om dataleveranciers en data-afnemers op weg te helpen, heeft TNO voor het betreffende registratieobject voorbeeldclients in Microsoft.NET C# en Java ontwikkeld (zie inlegvel, punt A). Deze applicaties bestaan uit objectclasses en clients, zoals beschreven wordt in de volgende paragrafen. Uiteraard is het ook mogelijk om geen gebruik te maken van (onderdelen van) deze voorbeeldclients. In de volgende paragrafen worden de mogelijkheden beschreven. 2.4 Objectclasses genereren Allereerst moeten de objectclasses gegenereerd worden. Hierbij zijn dataleveranciers en data-afnemers vrij om wel of niet gebruik te maken van de handreikingen in Microsoft.NET C# en Java. Wilt u gebruikmaken van die handreikingen, dan vindt u in de documentatie van de voorbeeldclients (zie inlegvel, punt A) uitleg hoe deze voorbeeldclients werken en hoe hergebruik van de objectclasses mogelijk is. 2.5 Clients bouwen Na het genereren van de objectclasses (geheel zelf gegenereerd of hergebruik van de objectclasses van de voorbeeldclients), is de volgende stap het bouwen van de clients. Hiervoor zijn meerdere mogelijkheden. Allereerst is voor de communicatie van de clients met de BRO een beveiligde verbinding nodig. Dit kan bij deze tweede stap van het aansluiten zowel met een PKIoverheid services server testcertificaat als een gebruikersnaam/wachtwoord combinatie.! De gebruikersnaam/wachtwoord combinatie is bedoeld om alvast te kunnen starten met de realisatie van de software. Uiteindelijk zal een client met een PKIoverheid services server testcertificaat gebouwd moeten worden om verder te kunnen met stap 3. Pagina 17 van 24

18 Vervolgens kan gekozen worden voor het zelf bouwen van de clients of het hergebruiken van de clients uit de voorbeeldclients in Microsoft.NET C# en Java (zie voor documentatie van voorbeeldclients inlegvel punt A). Voor welke optie ook gekozen wordt (zelfbouw of hergebruik met een PKIoverheid services server testcertificaat of gebruikersnaam/wachtwoord combinatie), uiteindelijk moeten de clients aangepast worden voor automatische gegevensuitwisseling met het softwaresysteem van de dataleverancier en data-afnemer. Hier stoppen de handreikingen van de BRO, aangezien dit voor elke dataleverancier en dataafnemer weer anders is. Wel wordt in de volgende paragraaf nog wat ondersteunende informatie gegeven. 2.6 Software bouwen of aanpassen Op basis van de beschreven documenten uit het hoofdstuk met praktische informatie moeten de dataleverancier en dataafnemer de software zelf verder bouwen of aanpassen. Om het gebruik van die documenten makkelijker te maken, zijn hieronder de belangrijkste kenmerken van die documenten samengevat. Catalogus Algemene kenmerken, begrippen en uitleg van het registratieobject Beschrijving registratieobject (entiteiten, attributen, domeinen) Inname- en uitgiftehandboeken Procesbeschrijving transacties Beschrijving van de berichten Beschrijving van de controles Beschrijving transactiegegevens (entiteiten, attributen, domeinen) Koppelvlakbeschrijvingen Technische specificatie koppelvlak Specificatie XML Schema transacties Specificatie XML Schema registratieobject Extra document: Testen verbinding webservices Beschrijving van testen verbinding met SoapUI Voorbeeldclients met toelichtend document Objectclasses en clients in Microsoft.NET C# Objectclasses en clients in Java In de koppelvlakbeschrijvingen komen een beschrijving van het registratieobject (gerelateerd aan de catalogus) en een beschrijving van de transactiegegevens (gerelateerd aan de inname- en uitgiftehandboeken) terug, maar dan verder uitgewerkt en vertaald in de bijbehorende XML Schema s. Onderstaand is daar een overzicht van gegeven. Pagina 18 van 24

19 Catalogus /Handboeken Naam attribuut Definitie Domeinwaarde Kardinaliteit Authenticiteit Toelichting Koppelvlakbeschrijvingen Naam attribuut in catalogus Naam element in XML Schema Voorbeeld waarde Toelichting + restricties Voorbeeld XML Naast deze documenten is voor sommige registratieobjecten nog een extra document beschikbaar: een handreiking voor conversie (indien van toepassing: zie inlegvel, punt A). 2.7 Communicatie met de BRO-webservices Tot slot is het handig om te weten hoe de communicatie met de BRO-webservices in hoofdlijnen verloopt. Allereerst kent elke transactie een verzoek en een daarbij behorende antwoord van de webservices van de BRO. Het antwoord geeft aan dat een verzoek is geaccepteerd, dan wel dat het verzoek is afgewezen met een reden. Als het verzoek niet valide is, bieden de innameen uitgiftehandboeken plus de koppelvlakbeschrijvingen informatie waarmee de software aangepast kan worden. Als de reden van afwijzing onvoldoende informatie bevat om het probleem op te lossen, kan de BRO Selfservicedesk benaderd worden met de vraag om op de serverlog te kijken wat eventueel de reden is. Hiervoor is dan wel de transactie-id nodig en het tijdstip van aanbieden. De transactie-id maakt onderdeel uit van iedere melding, zoals ook beschreven in het inname- en uitgiftehandboek. Als een registratie in de BRO succesvol is verlopen, krijgt het registratieobject een identificatiecode: een BRO-ID. In de inregelomgeving is de BRO-ID overigens een fictieve identificatiecode. Resultaat Als het met de documentatie (zie inlegvel, punt A) gelukt is om de koppelvlakken van de client software te ontwikkelen of aan te passen, is deze stap van realisatie van de software afgerond. De webservice cliënt moet nu in staat zijn automatisch gegevens aan te bieden en/of op te vragen bij de BRO. Nu kan verder gegaan worden met de aansluittoets in stap 3.! Neemt u deel aan de pilot of ketentest? Dan zijn stap 3 en 4 voor u niet van toepassing. In de opdrachtomschrijving van de pilot of ketentest staat nadere informatie wat u moet doen. Pagina 19 van 24

20 Stap 3: Aansluittoets Start 1 Dataleverancier/ data-afnemer Stap 1: Toegang Basisregistratie Ondergrond (BRO) 2 Stap 2: Realisatie 3 1. Registreren Stap Stap 3: Aansluittoets 3: Test Pilot/ Ketentest Inregel Omgeving 4 Stap 4: Definitieve aansluiting Productie omgeving Einde Systeem van de dataleverancier/ data-afnemer Systeem van de BRO Inleiding Werkt de client software? Dan volgt nu de aansluittoets ofwel proef van bekwaamheid om te kijken of de client software productierijp is. Hoewel deze aansluittoets plaatsvindt in de inregelomgeving, kan in deze stap niet de gebruikersnaam/wachtwoord combinatie gebruikt worden. Voor de aansluittoets moet het PKIoverheid services server testcertificaat gebruikt worden (zie stap 1.3). Is de aansluittoets succesvol doorlopen, dan kan de dataleverancier of dataafnemer met het bewijs daarvan door naar stap 4. Middelen Voor het uitvoeren van deze stap zijn de volgende middelen nodig: De aansluittoets: aanvragen via de Selfservicedesk van de BRO ( Pagina 20 van 24

21 De documentatie van het betreffende registratieobject (zie inlegvel, punt A).! Stap 3 kan alleen succesvol worden afgerond als de aansluittoets wordt uitgevoerd met een PKIoverheid services server testcertificaat. Uitleg en acties Uitgangspunt van de aansluittoets is dat de client software in de inregelomgeving met een PKIoverheid services server testcertificaat al goed werkt. Vervolgens wordt met de aansluittoets gekeken of de client software op de juiste wijze is aangesloten op de BRO. Deze aansluittoets bestaat veelal uit het aanleveren van gegevens van een beperkt aantal registratieobjecten volgens het kwaliteitsregiem van de BRO (IMBRO en/of IMBRO/A), het verwerken van een foutief aangeleverd registratieobject en het corrigeren van een registratieobject. Het gebouwde systeem moet immers verzoeken kunnen versturen naar de BRO en de antwoorden op de verzoeken vanuit van de webservices adequaat kunnen afhandelen. De transacties van de client software moeten geen verstoring in de BRO veroorzaken. De aansluittoets is daarom een minimale test die op een afgesproken datum en tijd moet worden uitgevoerd. Op die manier kan de technische systeemlogging uitwijzen welke meldingen in het systeem worden gedaan en of aanpassingen in de client software van de dataleverancier of data-afnemer noodzakelijk zijn. Vraag via de BRO Selfservicedesk de aansluittoets aan. Vervolgens maakt de BRO Selfservicedesk een afspraak wanneer de toets uitgevoerd kan worden. De inregelomgeving wordt dan voor dat dagdeel opgeschoond. Oude testgegevens van de dataleverancier of data-afnemer worden verwijderd. Vervolgens kan op het afgesproken dagdeel de aansluittoets worden uitgevoerd. Zodra de aansluittoets succesvol is afgerond, verleent de BRO Selfservicedesk toegang tot de productieomgeving.! Definitieve vastlegging van gegevens kan alleen in de productieomgeving. Gegevens die vastgelegd worden in de inregelomgeving, worden dus niet overgezet naar de productieomgeving. Op verzoek kan de inregelomgeving worden opgeschoond. Oude testgegevens worden dan verwijderd. Pagina 21 van 24

22 Resultaat Het succesvol afronden van de aansluittoets geeft het recht om aan te leveren aan de BRO voor het betreffende registratieobject. Alle stappen zijn immers succesvol afgerond. Met het bewijs daarvan en een PKIoverheid services server productiecertificaat, kan in de volgende stap aangesloten worden op de officiële productieomgeving van de BRO. Pagina 22 van 24

23 Stap 4: Definitieve aansluiting Start 1 Dataleverancier/ data-afnemer Stap 1: Toegang Basisregistratie Ondergrond (BRO) 2 Stap 2: Realisatie 3 1. Registreren Stap Stap 3: Aansluittoets 3: Test Pilot/ Ketentest Inregel Omgeving 4 Stap 4: Definitieve aansluiting Productie omgeving Einde Systeem van de dataleverancier/ data-afnemer Systeem van de BRO Inleiding De vierde stap is het moment waarop de dataleverancier of data-afnemer toegang krijgt tot de officiële BRO omgeving. Alle stappen in de inregelomgeving zijn immers succesvol doorlopen. In deze stap zullen in de client software een paar kleine aanpassingen nodig zijn, omdat het systeem van de dataleverancier of data-afnemer niet meer met de inregelomgeving communiceert, maar met de productieomgeving. Middelen Voor het uitvoeren van deze stap is het volgende nodig: PKIoverheid services server productiecertificaat. Pagina 23 van 24

24 Uitleg en acties Omdat het systeem van de dataleverancier of data-afnemer niet meer met de inregelomgeving communiceert, maar met de productieomgeving zijn een paar aanpassingen nodig in de client software. De software moet geconfigureerd worden voor de productieomgeving van de BRO. Zo heeft de productieomgeving een andere url dan de inregelomgeving.! Zodra de Algemene Maatregel van Bestuur van kracht wordt, naar verwachting 1 juli 2017, is het ministerie van Infrastructuur en Milieu niet meer de tijdelijke bronhouder. Bent u dataleverancier namens een bronhouder? Dan moet u vanaf dat moment uw rechten wijzigen (zie stap 1.1). In de productieomgeving kan de aangepaste configuratie overigens niet getest worden als het gaat om het registreren of corrigeren van gegevens.! Alle geregistreerde objecten krijgen in de productieomgeving een BRO-ID. Een registratieobject waaraan een BRO-ID is toegekend kan via de webservice niet meer verwijderd worden. Als onjuiste gegevens zijn aangeleverd, kan men door middel van een correctie wel een registratieobject wijzigen dat al in de BRO aanwezig is. Resultaat Zodra deze configuratie in stap 4 is afgerond, is het systeem van de dataleverancier of data-afnemer voor het betreffende registratieobject definitief aangesloten op de BRO. Vanaf dat moment kunnen registratieobjecten geregistreerd, opgevraagd of gecorrigeerd worden. Mocht een dataleverancier of data-afnemer nog vragen hebben, dan kan contact opgenomen worden met de Selfservicedesk van de BRO: Pagina 24 van 24