AANSLUITEN BRONHOUDERS OP DE LANDELIJKE VOORZIENING WOZ MET OPENTUNNEL 1.6

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z

AANSLUITEN BRONHOUDERS OP DE LANDELIJKE VOORZIENING WOZ MET OPENTUNNEL 1.6

WWW.OPENTUNNEL.NL  [email protected] WWW.JNET.NL

VERSIE 1.0


INHOUDSOPGAVE

Inhoudsopgave ...................................................................................................................................................................... 2 Inleiding ................................................................................................................................................................................... 3 Digikoppeling ......................................................................................................................................................................... 3 COMMUNICATIE TUSSEN BRONHOUDER/GEMEENTE EN LV-‐WOZ ...................................................................... 3 EBMS COLLABORATION PROTOCOL AGREEMENT (CPA) ........................................................................................ 3 AANLEVEREN BIJHOUDINGSBERICHTEN AAN OPENTUNNEL ............................................................................. 13 AANGEBODEN SERVICES LV-‐WOZ ................................................................................................................................ 16 CONFIGURATIE OPENTUNNEL BIJ BRONHOUDER .................................................................................................. 17 TUNNEL CONFIGURATIE BIJ BRONHOUDER ............................................................................................................. 19 LADEN VAN CPA IN OPENTUNNEL ................................................................................................................................ 24 ARCHIVERING VAN BERICHTEN .................................................................................................................................... 27


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z INLEIDING OpenTunnel is een integratiemakelaar en enterprise servicebus oplossing met ondersteuning voor alle Digikoppeling protocollen. Hieronder wordt uit de doeken gedaan hoe bronhouders via OpenTunnel met hun systemen kunnen aansluiten op de Landelijke Voorziening WOZ. Bijzonder is dat de Landelijke Voorziening zelf ook is gerealiseerd met OpenTunnel. Er is ook een aansluitdocument voor afnemers van de LV-WOZ in ontwikkeling. Deze richt zich op het bevragen van de LV-WOZ via ebMS (asynchrone bevragingen met indirecte leveringen), WUS (synchrone bevragingen met een onmiddellijk antwoord) en de inzet van de OpenTunnel Grote Berichten Standaard Plugin voor het afleveren van de response op asynchrone bevragingen. Een bronhouder kan ook afnemer zijn, dus ook dit document voor afnemers kan relevant zijn. Maar dit document richt zich specifiek op het aanleveren van gegevens aan de LV-WOZ en is bedoeld voor leveranciers van WOZ systemen, gemeenten met zelfgebouwde WOZ systemen en geïnteresseerden die inzicht willen krijgen hoe OpenTunnel systemen kan koppelen aan Landelijke Voorzieningen.

DIGIKOPPELING Digikoppeling (voorheen de Overheidsservicebus) is de 'postbode' voor de overheid. Digikoppeling bestaat uit een set standaarden voor elektronisch berichtenverkeer tussen overheidsorganisaties. Door deze eOverheid standaarden te adopteren kunt u digitaal berichten uitwisselen met collega-overheidsorganisaties. Landelijke registraties zoals het Omgevings Loket Online en de Landelijke Voorziening WOZ maken gebruik van Digikoppeling voor de gegevensuitwisseling. Digikoppeling is een protocolfamilie die nu bestaat uit ebMS 2.0, WUS en de Grote Berichten Standaard. De Landelijke Voorziening WOZ (LVWOZ) maakt gebruik van al deze protocollen.

COMMUNICATIE TUSSEN BRONHOUDER/GEMEENTE EN LV-WOZ Tussen bronhouder en LV wordt voor het aanleveren van gegevens gebruik gemaakt van betrouwbare uitwisseling door middel van het ebMS 2.0 protocol.

COMMUNICATIE TUSSEN AFNEMER EN LV-WOZ Afhankelijk van het type afnemer staan er meerdere kanalen ter beschikking om de LV-WOZ te bevragen. Een bronhouder kan natuurlijk ook optreden als afnemer. Tussen afnemer en LV wordt voor asynchrone bevragingen gebruik gemaakt van betrouwbare uitwisseling door middel van het ebMS 2.0 protocol. Synchrone bevragingen (vraag met een direct antwoord) gaan via webservices volgens het Digikoppeling WUS 2.0 profiel. Asynchrone (massale) bevragingen gaan op een bijzondere manier. De vraag wordt zoals hierboven gesteld aangeleverd via ebMS. Het antwoord wordt asynchroon in de vorm van een bestand geleverd via de Grote Berichten Standaard. Een gemeente kan zich eventueel ook abonneren op de levering van WOZ mutaties die (waarschijnlijk) via Digilevering gerealiseerd zal worden.

Indien een bronhouder de uitvoering van de WOZ administratie heeft uitbesteed aan een

samenwerkingsverband kan toch worden beschikt over WOZ gegevens via massale bevragingen of een Digilevering abonnement. Voor afnemer communicatie met de LV-WOZ op basis van OpenTunnel is een ander document beschikbaar: ‘Aansluiten afnemers op de Landelijke Voorziening WOZ met OpenTunnel 1.6’. WWW.OPENTUNNEL.NL  [email protected] WWW.JNET.NL

VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z EBMS COLLABORATION PROTOCOL AGREEMENT (CPA) Het berichtenverkeer tussen bronhouders en de landelijke voorziening wordt gereguleerd door een contract tussen twee partijen, de CPA. Hier worden de berichtsoorten en de eisen die gesteld worden aan de service gedefinieerd. Er is sprake van tweerichting verkeer, er gaan berichten van bronhouder naar LV-WOZ (dienstberichten) en tussen LV-WOZ en bronhouder (asynchrone foutberichten en verzoeken tot synchronisatie). De berichtuitwisselingen zijn gebaseerd op de WOZ berichtencatalogus zoals gedefinieerd door de Waarderingskamer. In de berichtcatalogus zijn ze gedefinieerd als WSDL. Ten behoeve van de communicatie tussen LV en bronhouder zijn er drie WSDL’s van toepassing: •

woz0312_ontvangAsynchroon_lv_mutatie_gemeente.wsdl

•

woz0312_ontvangAsynchroon_lv_mutatie_lv.wsdl

•

woz0312_ontvangAsynchroon_aansluitproces.wsdl

Om de beheerinspanning te reduceren zijn de berichttypen zoals gedefinieerd in de WSDL in één CPA opgenomen. Alleen voor het gebruik van asynchrone leveringen en abonnementen op mutaties via Digilevering zijn eventueel nog extra CPA’s nodig. Beide partijen in de twee-zijdige communicatie (LV en bronhouder) importeren de CPA en realiseren daarmee de verbinding, afgezien van de eisen die worden gesteld aan de netwerkverbindingen. De CPA is opgezet volgens het ebms 2.0 Digikoppeling profiel osb-rm. Dit houdt in dat de berichten verstuurd worden met een betrouwbaar profiel. Het partyId (OIN) in CPA en ebMS bericht identificeert de bronhouder. Het TLS certificaat waarmee de beveiligde HTTPS sessie wordt opgezet identificeert de zender. De zender mag dus ook een andere partij zijn, bijvoorbeeld een samenwerkingsverband. De zender wordt herkend aan de hand van de OIN van deze partij in het certificaat. In onderstaande tabel worden de berichttypen en profielen opgesomd: Berichtnaam nnpSa01 nnpSa03 npsSa01 npsSa03 swoSa01-lvwoz swoSa03-lvwoz swoSh01-lvwoz swoSh03-lvwoz vesSa01 vesSa03 wozSa01-lvwoz wozSa03-lvwoz wozSh01-lvwoz wozSh03-lvwoz wrdSa01-lvwoz wrdSa03-lvwoz wrdSh01-lvwoz wrdSh03-lvwoz BSKMB_Di01 BSWO_Di01 BWOZ_Di01 IBB_Di01 MBAG_Di01 MBE_Di01 MBG_Di01 MEL_Di01

Van Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente

Naar LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ


Digikoppeling profiel osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z MHEF_Di01 MKEN_Di01 MKOZ_Di01 MSUB_Di01 NBSK_Di01 OSWO_Di01 OWOZ_Di01 UBB_Di01 VBSK_Di01 WASWO_Di01 WAWOZ_Di01 WGEM_Di01 WWSP_Di01 leegDatabaseDi01 (alleen CT, AT,ET) leegDatabaseDu01 (alleen CT, AT,ET) nnpSa03 npsSa03 swoSh03-lvwoz vesSa03 wozSh03-lvwoz wrdSh03-lvwoz StUF:Fo01 StUF:Fo03

Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente LVWOZ Gemeente Berichtuitwisseling tussen bronhouder/gemeente en LV-WOZ

osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm osb-rm

Bij het vaststellen van de Digikoppeling-ebMS Servicespecificatie zijn lessen getrokken uit ervaringen met andere Landelijke Voorzieningen. Zo is de geldigheid van de CPA bepaald op 10 jaar. Dit betekent in de praktijk dat de PKI-o certificaten de levensduur van de servicerelatie bepalen (standaard 3 jaar). Bij het vervangen van deze certificaten hoeft de CPA niet te worden aangepast. Dit vermindert de beheerlast aanzienlijk. Via een aangepaste ‘persistDuration’ van 4 dagen zal een ebMS adapter gedurende 4 dagen proberen een bericht alsnog af te leveren. Dit betekent dat indien onverhoopt een Digikoppeling adapter niet beschikbaar is tijdens een weekend het bericht na een herstart alsnog zal worden afgeleverd. Een van de verplichte onderdelen van een CPA vormen de certificaten die een rol spelen bij de uitwisseling van de berichten. Deze certificaten kunnen worden geïmporteerd in OpenTunnel als onderdeel van de CPA import of kunnen separaat worden geladen en dus ook worden vervangen zonder dat de CPA wordt ‘geraakt’. Dit sluit aan op de best practices van Digikoppeling zoals door Logius is geadviseerd. De bouwstenen voor een CPA volgens Digikoppeling zijn een ebMS Service Specificatie en een ebMS consumerspecificatie. De service specificaties zijn door JNet gemaakt en gepubliceerd in het Digikoppeling serviceregister bij Logius onder de bedrijfservice naam WDK.WOZ0312.GEM.ontvangAsynchroon. De ebMS consumerspecificatie moet worden gemaakt ten behoeve van iedere bronhouder. Hieronder tonen wij een voorbeeld: <params> <partner name="gemeente"> <parameter name="CPAID" required="false"> <parameter name="StartDate" required="false">2012-05-01T00:00:00Z <parameter name="EndDate" required="false">2022-05-01T00:00:00Z <parameter name="PartyName" required="true"/> <parameter name="PartyId" required="true"/>


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z <parameter name="PartyIdType" required="false"/> <parameter name="PartyRef" required="false"/> <parameter name="EndpointUri" required="true"/> <parameter name="EndpointUriHTTP" required="false"/> <parameter name="ClientCert" required="true"/> <parameter name="ServerCert" required="true"/> <parameter name="Retries" required="false"/> <parameter name="RetryInterval" required="false"/> <parameter name="PersistDuration" required="false"/> <parameters name="gemeente"> <parameter name="PartyName">OnsDorp <parameter name="PartyId">00000001807390057000 <parameter name="PartyIdType">urn:osb:oin <parameter name="PartyRef">http://www.jnet.nl <parameter name="EndpointUri">https://someserver/opentunnel/00000001807390057000/ebms/lvwoz/intg <parameter name="EndpointUriHTTP">http://someserver/opentunnel/ 00000001807390057000/ebms/lv-woz/intg <parameter name="StartDate">2012-05-01T00:00:00Z <parameter name="EndDate">2022-05-01T00:00:00Z <parameter name="Retries">32 <parameter name="RetryInterval">PT3H <parameter name="PersistDuration">P4D <parameter name="ServerCert"> ........... <parameter name="ClientCert"> ...............


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z Een van de voorwaarden voor een bronhouder om toegang te krijgen tot de LV-WOZ is het verkrijgen van een CPA. Deze wordt aangevraagd bij de CPA creatievoorziening van Logius (https://www.cpa.serviceregister.overheid.nl/). De beheerder van de Landelijke Voorzieningen krijgt dan via mail ook een kopie van de CPA. Indien de CPA bij zowel bronhouder / samenwerkingsverband als Landelijke Voorziening wordt geladen is de verbinding tot stand gebracht (afgezien van allerlei maatregelen op netwerkniveau zoals inregelen firewall). Toegang tot de Landelijke Voorziening kan zowel via DigiNetwerk als via Internet. Hiervoor zijn separate CPA sjablonen (Servicespecificaties) beschikbaar bij de creatievoorziening. Voordat een organisatie als zendende partij toegang kan krijgen tot de conformiteitstoetsdienst, externe testdient voor leveranciers, aansluittoetsdienst of normale dienst in de productieomgeving dient de organisatie te beschikken over een productie PKI-Overheids servercertificaat met daarin opgenomen een HandelsRegisterNummer (HRN) of OverheidsIdentificatieNummer (OIN) van de organisatie. Meer informatie over Digikoppeling en de verkrijging van een OIN kunt u vinden op de volgende URL: http://www.logius.nl/producten/gegevensuitwisseling/digikoppeling/ Meer informatie over het aanvragen van CPA’s kunt u vinden op de volgende URL: https://www.cpa.serviceregister.overheid.nl/Handleiding_CPA_creatievoorziening_v1.3_.pdf. Hoofdstuk 5 bespreekt de stappen die een service requester dient uit te voeren. Indien een bronhouder de WOZ uitvoering heeft gedelegeerd aan een samenwerkingsverband dan is het certificaat in de CPA die van het samenwerkingsverband. De laatste partij verzendt en ontvangt de berichten. Ook het transport-endpoint in de CPA is die van het samenwerkingsverband! In de regel worden bovenstaande activiteiten door de leverancier (JNet) uitgevoerd die hier veel ervaring mee heeft. In het kort de stappen uit te voeren door een service requester (bronhouder/leverancier): 1.

KeyInfo uit certificaat halen via URL https://www/cpa.serviceregister.nl/keyinfo

2.

Aanpassen sjabloon t.b.v. Digikoppeling ebMS Consumer specificatie. De keyinfo uit de vorige stap moet worden geplakt in het bestand bij de elementen ClientCert en ServerCert.

3.

Het aanvragen van de CPA via URL https://www/cpa.serviceregister.nl/sr. Voor de LV-WOZ dienen de volgende stappen worden uitgevoerd: a.

Het invoeren van het ServiceID. Deze kunnen worden gevonden in het Digikoppeling ServiceRegister. Per omgeving zijn er voor de verschillende diensten en mogelijke wijze van toegang (internet en diginetwerk) Digikoppeling ebMS Servicespecificaties opgenomen. Dit aantal kan oplopen tot 12. De lijst met service-IDs wordt ook hieronder getoond. Ze zijn nog niet allemaal beschikbaar in het Digikoppeling serviceregister. ServiceID WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.NORMAAL.INET WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.CTO.INET

Omgeving

Dienst

Verbinding

Integratie

Normaal (standaard dienst)

internet

Integratie

Conformiteittoets

internet


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.ATO.INET

Integratie

Aansluittoets

internet

Functionele


internet

Conformiteittoets

internet

Aansluittoets

internet

Productie


internet

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.CTO.INET

Productie

Conformiteittoets

internet

WDK.WOZ0312.GEM.ontvangAsynchroon. PROD.ATO.INET

Productie

Aansluittoets

internet

WDK.WOZ0312.GEM.ontvangAsynchroon. PROD.ETO.INET

Productie

Leverancierstest

internet

Productie


Diginetwerk

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.CTO.DIGINET

Productie

Conformiteittoets

Diginetwerk

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.ATO.DIGINET

Productie

Aansluittoets

Diginetwerk

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.ETO.DIGINET

Productie

Leverancierstest

Diginetwerk

WDK.WOZ0312.GEM.ontvangAsynchroon.FTO.NORMAAL.INET

test Functionele

WDK.WOZ0312.GEM.ontvangAsynchroon.FTO.CTO.INET

test Functionele

WDK.WOZ0312.GEM.ontvangAsynchroon.FTO.ATO.INET

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.NORMAAL.INET

WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.NORMAAL.DIGINET

test


VERSIE 1.0


b.

Het selecteren van de in stap 2 voorbereide consumerspecificatie


VERSIE 1.0


c.

Het vullen van de start- en eind-datum. Door een bug in de creatievoorziening wordt de geldigheidstermijn gedefinieerd in de consumer specificatie niet overgenomen. De startdatum dient vandaag te zijn, de einddatum 10 jaar in de toekomst. Zo wordt voorkomen dat een CPA elk jaar moet worden vervangen. Het certificaat is maximaal 3 jaar geldig. Het certificaat bepaalt dan tevens de geldigheidstermijn van de koppeling.


VERSIE 1.0


d.

Het vullen van de juiste rolnamen: ‘LVWOZ’ voor de publisher rol en ‘gemeente’ voor de consumerrol

e.

Het invullen van uw naam en emailadres. Na het drukken op versturen kunt u de CPA downloaden. De publisher (Landelijke Voorziening) krijgt de CPA via email toegezonden.


VERSIE 1.0



VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z AANLEVEREN BIJHOUDINGSBERICHTEN AAN OPENTUNNEL OpenTunnel biedt vele opties hoe berichten aangeleverd kunnen worden. Dit speelt zowel op berichtinhoud als op protocolniveau. Op berichtniveau ondersteunt OpenTunnel standaard de volgende formaten: •

WOZ 3.12 StUF-XML

•

SOAP bericht met als body WOZ 3.12 StUF-XML

•

SOAP bericht met een WS-Addressing SOAP Header met als body WOZ 3.12 StUF-XML

Indien de WS-Addressing info dezelfde action naam bevat als die nodig is in het ebMS bericht kunnen deze worden overgenomen. Maar OpenTunnel kan ook geconfigureerd worden met tunnelvariabelen die de waarden uit de input koppelt aan de uitgaande ebMS berichten (zie tabellen hieronder). Dit maakt het omgaan met Digikoppeling vanuit het perspectief van een belastingsysteem een stuk eenvoudiger. Een van de doelstellingen van OpenTunnel is immers de eisen die Digikoppeling stelt te verbergen voor interne systemen. Toekomstige wijzigingen in de Digikoppeling standaard zullen dan geen invloed hebben op deze systemen. In bijzondere gevallen kan OpenTunnel ook met volledig andere in– en output formaten overweg waarbij OpenTunnel zorg draagt voor de omzetting naar StUFberichten. Hierbij is dan wel sprake van maatwerk waarvoor in OpenTunnel transformaties moeten worden gedefinieerd.

StUF:Functie in Di01 WOZ-BSKMB WOZ-BSWO WOZ-BWOZ WOZ-IBB WOZ_MBAG WOZ-MBE WOZ-MBG WOZ-MEL WOZ-MHEF WOZ-MKEN WOZ-MKOZ WOZ-MSUB WOZ-NBSK WOZ-OSWO WOZ-OWOZ WOZ-UBB WOZ-VBSK WOZ-WASWO WOZ-WAWOZ WOZ-WGEM WOZ-WWSP aansluitproces_leegDatabase

Root element naam ebMS action BSKMB_Di01 BSKMB_Di01 BSWO_Di01 BSWO_Di01 BWOZ_Di01 BWOZ_Di01 IBB_Di01 IBB_Di01 MBAG_Di01 MBAG_Di01 MBE_Di01 MBE_Di01 MBG_Di01 MBG_Di01 MEL_Di01 MEL_Di01 MHEF_Di01 MHEF_Di01 MKEN_Di01 MKEN_Di01 MKOZ_Di01 MKOZ_Di01 MSUB_Di01 MSUB_Di01 NBSK_Di01 NBSK_Di01 OSWO_Di01 OSWO_Di01 OWOZ_Di01 OWOZ_Di01 UBB_Di01 UBB_Di01 VBSK_Di01 VBSK_Di01 WASWO_Di01 WASWO_Di01 WAWOZ_Di01 WAWOZ_Di01 WGEM_Di01 WGEM_Di01 WWSP_Di01 WWSP_Di01 leegDatabaseDi01 leegDatabaseDi01 MAPPING StUF dienstberichten naar SOAP / ebMS actions

Root element naam nnpSa01 nnpSa03

ebMS action nnpSa01 nnpSa03


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z npsSa01 npsSa01 npsSa03 npsSa03 swoSa01-lvwoz swoSa01-lvwoz swoSa03-lvwoz swoSa03-lvwoz swoSh01-lvwoz swoSh01-lvwoz swoSh03-lvwoz swoSh03-lvwoz vesSa01 vesSa01 vesSa03 vesSa03 wozSa01-lvwoz wozSa01-lvwoz wozSa03-lvwoz wozSa03-lvwoz wozSh01-lvwoz wozSh01-lvwoz wozSh03-lvwoz wozSh03-lvwoz wrdSa01-lvwoz wrdSa01-lvwoz wrdSa03-lvwoz wrdSa03-lvwoz wrdSh01-lvwoz wrdSh01-lvwoz wrdSh03-lvwoz wrdSh03-lvwoz nnpSa03 nnpSa03 npsSa03 npsSa03 swoSh03-lvwoz swoSh03-lvwoz vesSa03 vesSa03 wozSh03-lvwoz wozSh03-lvwoz wrdSh03-lvwoz wrdSh03-lvwoz Fo01Bericht StUF:Fo01 Fo03Bericht StUF:Fo03 Bv03Bericht StUF:Bv03 Mapping StUF synchronisatie en foutberichten naar ebMS actions

De koppeling tussen binnenkomend bericht en uitgaand ebMS bericht moet worden gedefinieerd in de tunnelconfiguratie. Een tunnel definieert hoe/waar een bericht binnenkomt, welke operaties op het bericht plaatsvinden en op welke plekken de output moet worden afgeleverd. Een ebMS contract (CPA) is op losse wijze gekoppeld aan een of meerdere tunnels. Bovendien kunnen meerdere CPA’s worden gekoppeld aan een tunnel. Om te bepalen welke CPA van toepassing is en welke meta-data in het uitgaande ebMS bericht moeten worden opgenomen zijn drie variabelen nodig die gebruikt worden bij de bepaling van het juiste partnership uit de CPA: •

‘action’. Deze wordt bepaald door het inkomende bericht. In het geval van een inkomend WOZ 3.12 StUF-XML bericht vanuit het belastingsysteem kan de waarde van ‘action’ gelijk zijn aan de naam van het eerste element in het bericht. Indien de mapping gebeurt op basis van de waarde van het StUF:functie element zoals getoond in bovenstaande tabellen dient een mapping tabel te worden gevuld voor deze variabele. Hieronder volgt een schermafdruk van deze runtime variabele in een ebMS tunnel (op basis van naam eerste element):


VERSIE 1.0


•

‘service’. De servicenaam uit de CPA.

•

otherPartyId. Het partyId van de andere zijde (kadaster vanuit bronhouder gezien, bronhouder vanuit kadaster gezien).

Voor service en otherPartyId moeten ook waarden worden toegekend of een tunnel variabele mapping. Bij het Kadaster wordt vanuit een tunnel met vele ‘parties’ / bronhouders gecommuniceerd. In dat geval moet er voor de variabele otherPartyId een mapping worden aangelegd tussen inputbericht of protocolproperty en uitgaand partyId (=OIN). Indien er sprake is van één partij kan worden volstaan met constante waarden. De mappings worden gedefinieerd als onderdeel van de CPA import wizard. Naast het berichtformaat zijn er voor bronhouders/leveranciers meerdere interne protocolopties om een bericht af te leveren bij OpenTunnel die deze via ebMS doorzet naar de Landelijke Voorziening WOZ. De meest voor de handliggende zijn HTTP(S), JMS en eventueel via filesysteem. Voor de laatste optie biedt OpenTunnel FileEntry- en FileExit-Points waarbij individuele of samengestelde StUF berichten verwerkt kunnen worden. Foutafhandeling op basis van het plaatsen van asynchrone retourberichten vanuit LV-WOZ in het filesysteem is lastig te implementeren. OpenTunnel kan alleen de aflevering in het filesysteem garanderen, niet de verdere verwerking. Transactioneel is dit dus niet sluitend te krijgen en gezien de forse hoeveelheid berichten verdient deze optie niet de voorkeur.


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z AANGEBODEN SERVICES LV-WOZ Ofschoon de Landelijke Voorzieningen benaderd worden via de Digikoppeling adapter is het nuttig inzicht te hebben in de diensten die de LV-WOZ ter beschikking stelt. Voor de LV-WOZ zijn er diverse omgevingen beschikbaar (productie, acceptatie, functionele testomgeving, integratie). Per omgeving worden er verschillende diensten afgenomen voor verschillende typen gebruikers: •

CT dienst voor het vaststellen van conformiteit van een leverancier

•

AT dienst voor de aansluittoets van gemeenten

•

ET dienst voor externe testen door leveranciers

•

Normale productie dienst voor gemeenten en afnemers

In iedere omgeving zijn al deze diensten opgenomen in één of meerdere OpenTunnel configuraties. Iedere dienst heeft zijn eigen entrypoints voor het aanleveren van berichten en bevragingen. Bovendien zijn deze entrypoints voorzien van een versienummer. Toekomstige versies van de WOZ berichtencatalogus krijgen dan een nieuwe URL waardoor er meerdere versies ondersteund kunnen worden. De LV-WOZ koppelt ook zaken terug aan de bronhouder systemen. Foutmeldingen en verzoeken tot synchronisatie worden vanuit LV-WOZ gedaan via ebMS protocol naar de lokale OpenTunnel broker. De verschillende diensten en een voorbeeld hoe omgegaan wordt met meerdere LV-WOZ versies wordt in onderstaand component diagram getoond.

OpenTunnel diensten in LV-WOZ omgeving bij Kadaster

De diensten worden dus onderscheiden door een contextpad (bijv: /lv-woz-ato/312/ebms/aanleveren). De omgevingen zelf worden onderscheiden door een DNS naam van het kadaster. De integratie-omgeving bijvoorbeeld heeft als DNS naam service30.integratie.kadaster.nl.


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z CONFIGURATIE OPENTUNNEL BIJ BRONHOUDER Een belastingapplicatie communiceert direct met OpenTunnel of via een ander systeem zoals een servicebus. De applicatie kan de volgende berichtensoorten uitsturen: 1.

Bijhoudingsberichten (StUF gebeurtenis georiënteerde dienstberichten volgens WOZ catalogus)

2.

StUF synchronisatieberichten (zelfstandig geïnitieerd of naar aanleiding van verzoek uit LV)

3.

Synchrone vraagberichten

4.

Asynchrone (massale) bevragingen

Berichtsoorten 1, 2 en 4 worden via ebMS uitgestuurd. De andere via het zogenaamde Digikoppeling WUS kanaal. Asynchrone en synchrone bevragingen gaan via eigen tunnels met een eigen URL. Het gewenste gedrag van OpenTunnel zal anders moeten zijn en behoeft derhalve een andere tunnel configuratie. De configuratie voor asynchrone bevragingen wordt besproken in een separaat document ‘Aansluiten afnemers op de Landelijke Voorziening WOZ met OpenTunnel 1.6’ OpenTunnel kan flexibel worden geconfigureerd maar hieronder doen we toch een suggestie hoe de tunnels kunnen worden aangesproken. De berichten worden door de belastingapplicatie ingeschoten in een entrypoint die onderdeel uitmaakt van een tunnel. Een OpenTunnel instantie kan gebruikt en geconfigureerd worden per LV-WOZ dienst maar er kunnen ook LV-WOZ diensten gedeeld worden . In onderstaand diagram worden de entrypoints voor de aansluittoets in dezelfde server opgenomen als waar de productie entrypoints zich bevinden. De verschillende diensten worden door een naamgevingsconventie uit elkaar gehouden. De aansluittoets-entrypoints zijn herkenbaar aan ‘ato’ in het contextpad (/lvwozato/….). De productie-entrypoints hebben geen aparte aanduiding (/lvwoz/…). De LV-WOZ tunnels communiceren via exitpoints met de LV-WOZ (die op haar beurt weer entrypoints heeft om de berichten op te vangen). OpenTunnel luistert behalve naar binnenkomende berichten van een interne belastingapplicatie ook naar berichten uit de LV-WOZ.


VERSIE 1.0


Voorbeeldconfiguratie OpenTunnel diensten bij de bronhouder op basis van HTTP(S)

De ebMS berichten die ontvangen kunnen worden uit de LV-WOZ zijn de volgende: 1.

StUF Foutberichten die doorgezet worden naar het belastingsysteem

2.

StUF synchronisatieberichten indien de LV-WOZ een volledig nieuwe opbouw wil maken van een WOZ object. Ook deze worden doorgezet aan het belastingsysteem.

3.

Berichten volgens de Digikoppeling Grote Berichten Standaard. Verzoeken voor een massale levering worden in eerste instantie door een belastingsysteem (of andere applicatie) via OpenTunnel doorgegeven aan de LV-WOZ. De Landelijke Voorziening verwerkt deze verzoeken in de achtergrond en maakt een bestand aan. Via ebMS wordt door het kadaster vanuit hun GDS2 systeem een notificatie gestuurd volgens de Digikoppeling Grote Berichten Standaard. Deze wordt door OpenTunnel aan de bronhouder/afnemer zijde opgevangen. De ingebouwde Grote Berichten Standaard implementatie in OpenTunnel zorgt ervoor dat het bestand via HTTPS wordt opgehaald en geplaatst wordt op een geconfigureerde locatie. Deze locatie wordt geconfigureerd in een ‘bestandstunnel’.

In bovenstaand figuur worden deze berichtsoorten verdeeld over twee entrypoints: WWW.OPENTUNNEL.NL  [email protected] WWW.JNET.NL

VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z Eén voor de LV-WOZ communicatie (berichtsoort 1 en 2 met entrypoint contextpad /opentunnel/ebms/lvwoz/ 312/terugkoppelinglevering/prd en één voor de Grote Berichten Standaard communicatie (/opentunnel/ebms/gb /10/gds2/prd). Ook kunt u uit deze figuur aflezen dat een CPA standaard is gekoppeld aan twee tunnels omdat de communicatie vanuit twee zijden kan worden opgebouwd.

TUNNEL CONFIGURATIE BIJ BRONHOUDER De ebMS communicatie voor het aanleveren van WOZ gegevens gaat in twee richtingen, er zijn daarom per omgeving-dienst combinatie twee tunnels nodig: 1.

Tunnel voor ontvangst van kennisgeving- en synchronisatieberichten vanuit het belastingsysteem en vervolgens doorzenden naar de LV-WOZ

2.

Tunnel voor ontvangst van foutberichten - en synchronisatieverzoeken vanuit de LV-WOZ naar het belastingsysteem of servicebus. De ebMS protocol bevestigingen komen hier ook binnen.

Deze tunnels met entrypoints en exitpoints moeten vooraf worden gedefinieerd. OpenTunnel kan zelf het TLS verkeer initiëren en beëindigen. Hiertoe moeten de juiste certificaten worden opgenomen in OpenTunnel, als stap in de CPA import of separaat. Maar in sommige gevallen vindt SSL offloading plaats. In dat geval wordt de inkomende SSL communicatie beëindigd op een Gateway of loadbalancer. Voor het uitgaande OpenTunnel kan d.m.v. HTTP headers een gateway / loadbalancer instrueren naar welke partij het bericht verstuurd moet worden. Voor iedere communicatiepartij kan dit worden opgenomen in een OpenTunnel mapping. Deze configuratiestap is onderdeel van de CPA import.


VERSIE 1.0


Routering uItgaand verkeer via proxy/loadbalancer gebruikmakend van HTTP header en een mapping tabel

Hieronder geven wij een voorbeeld van mogelijke entrypoints die gedefinieerd kunnen worden voor de standaard dienst in de LV-WOZ. Ieder entrypoint wordt opgenomen in een tunneldefinitie die bepaalt welke verwerking het bericht ondergaat en waar en hoe het afgeleverd moet worden. De entrypoints zijn hier gebaseerd op HTTP(S). Voor het externe Digikoppeling verkeer is dit verplicht. Bij de aansluiting van een belastingsysteem of servicebus op de Digikoppeling adapter biedt OpenTunnel meer protocollen om uit te kiezen.

EntryPoint Naam

Bronhouder naar LV-WOZ Aanleveren Entrypoint

Contextpad van URL

Intern Extern

/opentunnel/lvwoz/aanleveren/ (intern is

intern

versienummering in URL niet nodig) /opentunnel/lvwoz/synchroon/

Bronhouder naar LV-WOZ synchrone vragen Entrypoint

/

(intern

is

intern

/opentunnel/lvwoz/asynchroon/ (intern is

intern

versienummering in URL niet nodig)

Bronhouder naar LV-WOZ asynchrone vragen Entrypoint

versienummering in URL niet nodig)

LV-WOZ naar Bronhouder ebMS terugkoppel Entrypoint

/opentunnel/ebms/lv-

Extern

woz/312/prd/aanleverenAntwoord (Dit entrypoint moet gelijk zijn aan het transportreceiver


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z endpoint in de CPA tenzij OpenTunnel niet zelf het TLS endpoint is, maar SSL offloading wordt toegepast) LV-WOZ naar Bronhouder ebMS terugkoppel Entrypoint

opentunnel/ebms/gb/10/gds2/prd

Extern

(optioneel indien gebruik gemaakt wordt van massale bevragingen)

Voorbeeld OpenTunnel entrypoints tbv LV-WOZ bij de bronhouder

In onderstaande schermafdruk ziet u een voorbeeld van een OpenTunnel entrypoint waar een belastingapplicatie haar berichten kan afleveren. In dit geval is gekozen voor HTTP en gewone StUF XML berichten. De contextpad syntax is voor de single-tenant versie.

Voorbeeld EntryPointConfiguratie voor berichten van belastingapplicatie naar LV-WOZ

Er is ook een entrypoint nodig waar de LV-WOZ haar berichten kan afleveren. Deze moeten gebruik maken van HTTPS, het berichtformaat is ebMS (met een StUF WOZ Payload). Aan dit entrypoint waarop OpenTunnel luistert naar inkomende berichten van de LV-WOZ is een certificaat gekoppeld. Dit certificaat maakt ook deel uit van de CPA maar kan ook separaat geïmporteerd zijn in de OpenTunnel certificaatkluis.


VERSIE 1.0


Voorbeeld EntryPointConfiguratie voor berichten van LV-WOZ naar belastingapplicatie

De volgende stappen zijn de definitie van de exitpoints (waar moet het bericht worden afgeleverd), transformaties (welke omzettingen er gepleegd worden op het bericht), verzoekprofielen (welke andere operaties er nodig zijn op bericht) en de tunnels waar entrypoint, exitpoint(s) en verzoekprofielen/transformer(s) aan elkaar worden gekoppeld en de servicekarakteristieken

worden

bepaald

(synchroon/asynchroon,

bewaartermijn,

archivering,

berichtvalidatie,

authenticatie/autorisatie, tunnelvariabelen voor parametrisering van transformaties etc). Nu presenteren wij de exitpoints waar OpenTunnel de LV-WOZ berichten aflevert. In dit overzicht is ook de asynchrone bevraging opgenomen die verder besproken wordt in het aansluitdocument voor afnemers.

ExitPoint Naam

Contextpad van URL

Intern Extern

ebMS LV-WOZ Productie

/lv-woz/312/ebms/aanleveren

Extern

/lv-woz/312/wus/beantwoordVraag

Extern

/lv-woz/312/ebms/asynchroneVraag

Extern

/

(Dit exitpoint moet gelijk zijn aan het transportreceiver endpoint in de CPA bij het kadaster als LV-WOZ beheerder) WUS Synchroon LV-WOZ Productie (Voor bevraging op LV-WOZ) ebMS Asynchrone Bevragingen LV-WOZ Productie (voor asynchrone (massale) bevragingen)


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z Terugkoppeling LV-WOZ naar bronhoudersysteem voor leveringen

(StUF

foutberichten

en

In overleg met leverancier/bronhouder

Intern

In overleg met leverancier/bronhouder

Intern

synchronisatie

verzoeken) Terugkoppeling LV-WOZ naar bronhoudersysteem voor asynchrone vragen (StUF foutberichten)

Voorbeeld OpenTunnel exitpoints tbv LV-WOZ bij de bronhouder

In onderstaande schermafdruk een voorbeeld van een exitpoint bestemd voor de aflevering van LV-WOZ berichten via ebMS naar het Kadaster als beheerder van de LV-WOZ. Er is bij Digikoppeling verkeer sprake van tweezijdig TLS/SSL verkeer vandaar dat ook de OpenTunnel server haar client-certifcaat aanbiedt tijdens het opzetten van de TLS/SSL verbinding.

Voorbeeld ExitPointConfiguratie voor berichten van belastingsysteem via OpenTunnel naar LV-WOZ

Berichtomzetting gebeurt in OpenTunnel met behulp van transformers. Dit kunnen sjablonen zijn gebaseerd op XSLT en FreeMarker of programatuur. Voor ebMS levert OpenTunnel standaard een transformer mee. Deze kan worden geparametriseerd met waarden van OpenTunnel run-time variabelen die opgenomen worden in de transformatie sjablonen. De runtime variabelen kunnen gebaseerd zijn op constanten (bijv. gemeentecode) of op basis van een element in het inkomend bericht of resultante van een OpenTunnel functie. OpenTunnel beschikt ook over een set run-time variabelen met een voorgedefinieerd gedrag. Denk aan generatie van tijdstip elementen, messageIDs en het ophalen en plaatsen in sjabloon van waarden uit een OpenTunnel mappingtabel. Transformers kunnen ook in een keten worden opgenomen zodat de output van ene transformer input is voor de volgende. Eerst kan een inkomend XML of tekst bericht worden aangepast en dan met een tweede transformer worden omgezet in een ebMS- of SOAP-bericht.


VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z LADEN VAN CPA IN OPENTUNNEL Hieronder volgt een beschrijving van de CPA import wizard van OpenTunnel. Deze wizard maakt het mogelijk een CPA te koppelen aan twee voorgedefinieerde tunnels (inkomend en uitgaand ten behoeve van ebMS tweerichting verkeer). Er kunnen vele CPA’s worden gekoppeld aan dezelfde tunnel hetgeen het beheer vereenvoudigd. Indien het uitgaande verkeer via een niet-transparante proxy verloopt (firewall, XML gateway, loadbalancer) kunnen routeringinstructies worden meegegeven in de vorm van HTTP headers. Dit kan ook worden geconfigureerd tijdens de import. Als u de multi-tenant versie van OpenTunnel gebruikt dient u eerst de juiste organisatie te selecteren. Er wordt namelijk gecontroleerd of de geselecteerde partij in OpenTunnel overeenkomt met een van de partijen in de CPA. OpenTunnel herkent ook de rol die de organisatie speelt in de CPA (gemeente of LV, SR of SP)

Druk op importeren en selecteer het CPA bestand. Na selectie wordt de CPA geanalyseerd, dit kan enkele tientallen seconden duren. Het CPA inhoud overzicht verschijnt dan:


VERSIE 1.0


In deze eerste stap kunt u de certificaten importeren voor zover deze nog niet bestaan. Met name kunnen op deze wijze de certificaten van de andere partij worden opgenomen in de OpenTunnel certificatenkluis. Op deze wijze geeft u aan deze te vertrouwen waardoor vanuit OpenTunnel een beveiligde sessie mag worden opgebouwd met de andere partij. De certificaten van uw eigen organisatie zullen wel reeds aanwezig zijn in OpenTunnel. Deze worden dan niet nogmaals geïmporteerd. Druk op volgende en u komt in de tweede stap waarbij u de mogelijkheid krijgt de CPA aan een ingaande en/of uitgaande tunnel te koppelen.


VERSIE 1.0


Selecteer eerst de inkomende tunnel en daarna de uitgaande tunnel door de juiste checkbox aan te vinken. Voor zover tunnelsettings anders zijn dan die in de CPA kunnen deze worden overgeschreven. Dit is aanbevolen omdat de CPA leidend dient te zijn. De laatste stap is het toevoegen van mappings voor action en otherPartyId. Met andere woorden: op welke CPA moet het uitgaande verkeer worden gebaseerd en naar welke partij moet het bericht worden gestuurd. Voor verkeer vanuit de bronhouder is dit eenduidig, er is maar 1 afleveradres. De andere partij kan dan worden opgenomen als constante. Indien deze gebaseerd is op een expressie (bijvoorbeeld de gemeentecode in een StUF bericht) dan kan een mapping worden toegevoegd tussen gemeentecode (bron) en het partyId van de bestemming (=OIN). Indien het exitpoint van de uitgaande tunnel niet wijst naar het daadwerkelijke endpoint maar naar een interne loadbalancer / firewall / proxy dan kan de proxy via http headers geïnstrueerd worden waar de berichten moeten worden afgeleverd. Indien de exitpoint van de uitgaande tunnel anders is dan die gedefinieerd is in de CPA dan wordt deze mapping optie geactiveerd. Het afleverendpoint uit de CPA is dan de doelwaarde, de bron kan bijvoorbeeld een gemeentecode zijn uit het StUF bericht of een tunnelvariabele.


VERSIE 1.0


Indien u op de knop ‘Afsluiten’ drukt wordt de CPA gekoppeld aan de geselecteerde tunnel(s).

ARCHIVERING VAN BERICHTEN Indien u als aanbieder van berichten aan de Landelijke Voorziening de verzonden en/of ontvangen berichten wilt bewaren voor een langere termijn kunt u gebruik maken van onze archiveringserver. De OpenTunnel runtime database wordt gebruikt voor betrouwbare aflevering van gegevens. Na aflevering worden deze normaliter verwijderd na een door u instelbare tijd. Deze runtime database is dus niet geschikt voor archivering voor bijvoorbeeld onweerlegbaarheidseisen. De OpenTunnel archiveringoplossing is zeer flexibel en schaalbaar. Er wordt gebruik gemaakt van een of meerdere aan elkaar gekoppelde MongDB servers voor horizontale schaalbaarheid en replicatie. De archiveringserver wordt aan OpenTunnel gekoppeld als exitpoint en in een tunnel opgenomen als archivering exitpoint. Berichten kunnen ook worden gearchiveerd in een DMS (via CMIS of FTP) of via WebDAV protocol, maar de archiveringserver biedt meer schaalbaarheid en de mogelijkheid om zelf de metadata bij een bericht/tunnel te definiëren en daar ook weer op te kunnen zoeken. Bij het archiveren kunnen vier stadia van berichtverwerking worden gearchiveerd: 1.

Zoals het bericht is binnengekomen

2.

Zoals het bericht is afgeleverd bij een exitpoint En indien er sprake is van een synchrone vraag/antwoord tunnel WWW.OPENTUNNEL.NL  [email protected] WWW.JNET.NL

VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z 3.

Zoals het antwoord is binnengekomen

4.

Zoals het antwoord is uitgeleverd

Hieronder een voorbeeld definitie van een achivering exitpoint:

Op de configuratie tab worden de parameters die nodig zijn voor de koppeling naar de MongDB NoSQL database. De database en collectie (tabel in relationele database terminologie) wordt dynamisch gecreeerd.

Hieronder volgt een voorbeeld configuratie voor de metadata. De parameters die gedefinieerd zijn worden dynamisch als WWW.OPENTUNNEL.NL  [email protected] WWW.JNET.NL

VERSIE 1.0

Integratiemakelaar en servicebus met volledige Digikoppeling connectiviteit z metadatakolommen toegevoegd aan de collectie. Deze metadata kolommen zijn ook doorzoekbaar via de gebruikersinterface van de archiveringserver. De metadata kunnen zoals iedere OpenTunnel variabele gebaseerd zijn op een waarde uit het brondocument, een constant, een resultante van een functie of de waarde van een andere tunnelvariabele.

De laatste stap die moet worden verricht is het koppelen van het zojuist gedefinieerde exitpoint aan een tunnel. Dit kan alleen indien aangegeven is dat het bericht moet worden gearchiveerd in een van de vier hierboven genoemde verwerkingstadia.


VERSIE 1.0

AANSLUITEN BRONHOUDERS OP DE LANDELIJKE VOORZIENING WOZ MET OPENTUNNEL 1.6

Recommend Documents