AANSLUITEN BRONHOUDERS OP DE LANDELIJKE VOORZIENING WOZ
VERSIE 1.2
INHOUDSOPGAVE Inhoudsopgave ...................................................................................................................................................................... 2 Inleiding ................................................................................................................................................................................... 3 Digikoppeling ......................................................................................................................................................................... 3 COMMUNICATIE TUSSEN BRONHOUDER/GEMEENTE EN LV-‐WOZ ...................................................................... 3 EBMS COLLABORATION PROTOCOL AGREEMENT (CPA) ........................................................................................ 3 AANGEBODEN SERVICES LV-‐WOZ ................................................................................................................................ 11 EBMS SERVICES BIJ BRONHOUDER .............................................................................................................................. 12
VERSIE 1.2
INLEIDING In dit document wordt beschreven hoe bronhouders via Digikoppeling met hun systemen kunnen aansluiten op de Landelijke Voorziening WOZ. Er is ook een aansluitdocument voor afnemers van de LV-WOZ in ontwikkeling. Deze richt zich op het bevragen van de LV-WOZ en de inzet van de Grote Berichten Standaard voor het afleveren van de response op massale bevragingen. Dit document is bedoeld voor leveranciers van WOZ systemen, gemeenten met zelfgebouwde WOZ systemen en geïnteresseerden die inzicht willen krijgen hoe men systemen kan koppelen aan Landelijke Voorzieningen alsmede functionarissen belast met de creatie van CPA’s ten behoeve van aansluiting bij de LV-WOZ.
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 gebruik gemaakt van een betrouwbare uitwisseling door middel van het ebMS 2.0 protocol. Bevragingen gaan via webservices volgens het Digikoppeling WUS 2.0 profiel. Asynchrone (massale) bevragingen gaan op een bijzondere manier. De vraag wordt gesteld via een webservice. 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 Digileveringabonnement.
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 WSDLs van toepassing: •
woz0312_ontvangAsynchroon_lv_mutatie_gemeente.wsdl
•
woz0312_ontvangAsynchroon_lv_mutatie_lv.wsdl VERSIE 1.2
•
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 massale leveringen en abonnementen op mutaties via Digilevering zijn eventueel nog extra CPA’s nodig. Beide partijen in de twee-zijdige commmunicatie (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 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
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 Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ
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 LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ LVWOZ Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente Gemeente
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 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.2
StUF:Fo01 StUF:Fo03
LVWOZ LVWOZ
Gemeente Gemeente Berichtuitwisseling tussen bronhouder/gemeente en LV-WOZ
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 als onderdeel van de CPA import of kunnen separaat worden geladen en dus ook worden vervangen zonder dat de CPA wordt ‘geraakt’. Indien het onderliggende certificaat verloopt behoeft de CPA niet te worden vervangen. 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 de bouwer van de LV-WOZ gemaakt en gepubliceerd in het Digikoppeling serviceregister bij Logius. 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"/> <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 VERSIE 1.2
<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"> ...............
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 VERSIE 1.2
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 Digikoppeling leverancier 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
Omgeving
Dienst
Verbinding
Integratie
Normaal (standaard dienst)
internet
WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.CTO.INET
Integratie
Conformiteittoets
internet
WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.ATO.INET
Integratie
Aansluittoets
internet
Functionele
Normaal (standaard dienst)
internet
Conformiteittoets
internet
Aansluittoets
internet
Productie
Normaal (standaard dienst)
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
Normaal (standaard dienst)
Diginetwerk
Productie
Conformiteittoets
Diginetwerk
WDK.WOZ0312.GEM.ontvangAsynchroon.INTG.NORMAAL.INET
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 WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.CTO.DIGINET
test
VERSIE 1.2
b.
WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.ATO.DIGINET
Productie
Aansluittoets
Diginetwerk
WDK.WOZ0312.GEM.ontvangAsynchroon.PROD.ETO.DIGINET
Productie
Leverancierstest
Diginetwerk
Het selecteren van de in stap 2 voorbereide consumerspecificatie
VERSIE 1.2
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.2
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.2
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 VERSIE 1.2
•
AT dienst voor de aansluittoets van gemeenten
•
ET dienst voor externe testen door leveranciers
•
Normale productie dienst voor gemeenten en afnemers
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 ebMS broker. De verschillende diensten en een voorbeeld hoe omgegaan wordt met meerdere LV-WOZ versies wordt in onderstaand component diagram getoond.
LV-WOZ diensten per 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.
EBMS SERVICES BIJ BRONHOUDER 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 VERSIE 1.2
instantie door een belastingsysteem (of andere applicatie) via de Digikoppeling WUS standaard aan de LV-WOZ kenbaar gemaakt. De Landelijke Voorziening verwerkt deze verzoeken in de achtergrond en maakt een bestand aan. Via ebMS wordt door het kadaster een notificatie gestuurd volgens de Digikoppeling Grote Berichten Standaard. Deze wordt door de ebMS adapter aan de bronhouder/afnemer zijde opgevangen. Het bestand dient vervolgens te worden gedownload.
VERSIE 1.2
