CPA Register gebruikershandleiding

Inleiding

Doel en scope van Digikoppeling

Digikoppeling biedt de mogelijkheid om op sterk gestandaardiseerde wijze berichten uit te wisselen tussen service providers (aanbieders) en service  requesters (afnemers of consumers).

De uitwisseling tussen service providers en requesters wordt in drie lagen opgedeeld:

• Inhoud: op deze laag worden de afspraken gemaakt de inhoud van het uit te wisselen bericht, dus de structuur, semantiek, waardebereiken etc.
  
  Digikoppeling houdt zich niet met de inhoud bezig, ‘heeft geen boodschap aan de boodschap’.
• Logistiek: op deze laag bevinden zich de afspraken betreffende transportprotocollen (HTTP), messaging (SOAP), beveiliging (authenticatie en encryptie)en betrouwbaarheid. Dit is laag van Digikoppeling.
• Techniek: deze laag verzorgt het daadwerkelijke routeren van de data (TCP/IP).

Digikoppeling richt zich dus uitsluitend op de logistieke laag. Deze afspraken komen in de koppelvlakstandaarden en andere voorzieningen.

Koppelvlak & koppelvlakstandaard

Een koppelvlak is een interface die volgens standaarden de gegevensuitwisseling verzorgt. Het werken met vaste standaarden is essentieel voor een koppelvlak, het vergemakkelijkt de implementatie. Ook wordt het mogelijk diverse soorten berichten door te sturen met een grote mate van interoperabiliteit.

Een van de belangrijkste eisen die de overheid stelt bij de inrichting van generieke voorzieningen is, dat er niet veel maatwerk ontwikkeld hoeft te worden. Het is beter als er van 'off the shelf', commercieel of OPEN source  software gebruik gemaakt kan worden. Voor de Bus, dus voor de logistieke laag, betreft dat het niet steeds willen ontwikkelen van software voor een koppelvlak.

Dit doel wordt bereikt (benaderd) door te kiezen voor internationaal (de jure of de facto) vastgelegde standaarden, die door 'alle' leveranciers interoperabel zijn geïmplementeerd.

Een andere eis is dat met name afnemers gebruik kunnen maken van één 'stekker' (één logistiek koppelpunt – zie hoofdstuk Leidend principe). 

Specificatie van de koppelvlakstandaard

De koppelvlakspecificatie beschrijft de eisen waar de adapters aan moeten voldoen om interoperabel met elkaar te kunnen communiceren. De hele set info die nodig is voor een complete Digikoppeling koppelvlakspecificatie is beschreven in het Digikoppeling profiel.

Opbouw van deze pagina

Hoofdstuk Leeswijzer is een leeswijzer voor deze pagina.

Hoofdstuk Gebruik van CPA's geeft een algemene informatie over het gebruik van CPA’s.

Hoofdstuk Stappenplan algemeen is bedoeld voor organisaties (in het algemeen: de 'Consumers') van services, ook wel aangeduid met service requester (SR). Dit hoofdstuk beschrijft de stappen om te komen tot een ECS en uiteindelijk een CPA.

Hoofdstuk Stappenplan Service Provider is bedoeld voor organisaties (in het algemeen: de 'Publishers') van services, ook wel aangeduid met serviceprovider (SP). Het beschrijft de handelingen nodig om te komen tot een Digikoppeling-ebMS Servicespecificatie (ESS)

Hoofdstuk API is bedoeld voor organisaties die via een API geautomatiseerd handelingen op het CPA register willen uitvoeren.

Leidend principe (requirement)

De koppelvlakstandaarden moeten leiden tot een maximum aan interoperabiliteit met een minimum aan benodigde ontwikkelinspanning.

Daarom werd gekozen voor bewezen interoperabele internationale standaarden.

Digikoppeling maakt berichtenuitwisseling mogelijk op basis van de ebXML/ebMS en WUS families van standaarden inclusief de daarbij behorende verwante standaarden.

Leeswijzer

In hoofdstuk Gebruik van CPA's vertellen we kort iets over het gebruik van CPA's. Daarna gaan we er dieper op in. Als gegevens op basis van Digikoppeling Koppelvlakstandaard ebMS [Digikoppeling-1.0] uitgewisseld moeten worden, is er een CPA nodig voor de configuratie van de ebMS adapter. Een organisatie vervult hierbij de rol van service requester (SR) of service provider (SP).

Figuur: een organisatie met SP rol bereidt een CPA voor.

Voor de beschrijving van het maken van een CPA beperken we ons tot de situatie met één SP en meerdere SR's. De SR zal het initiatief nemen tot het creëren van een relatie met een SP, en daarmee tot het creëren van een CPA. De SP zal echter het voorbereidende werk moeten doen ten aanzien van het opstellen van de specificatie van de berichten en het aangeven van de ontbrekende gegevens (die nog door de SR opgegeven moeten worden).

Het handmatig construeren van een CPA is een technisch, lastig en bewerkelijk proces. Daarom is er een webinterface en een wizzard gemaakt waarmee een CPA gemaakt kan worden. Het CPA Register geeft desondanks de mogelijkheid om zelf gemaakte ESS, ECS, en CPA te uploaden voor gebruik door de andere partij.

U kunt ook een bedrijf inhuren om voor u CPA’s te maken. U moet hen daarvoor wel machtigen. Hoe u dat doet leest u in hoofdstuk Stap 3: Service provider machtigen (optioneel).

Globaal ziet het invoerproces voor een SR er zo uit (hoofdstuk Stappenplan algemeen):

1. Organisatie invoeren
2. Personen invoeren binnen een organisatie (gebruiker registreren)
3. Andere personen machtigen door een geregistreerde gebruiker (optioneel)
4. Digikoppeling profielen invoeren
5. CPA aanmaken

Na(ast) het invoerproces kan een gebruiker zijn/haar Digikoppelingen inclusief certificaten én CPA’s vervolgens gaan beheren.

Een SP moet (een) service(s) klaarzetten en publiceren om later door een SR te worden gebruikt om CPA’s te maken. Hoofdstuk Stappenplan Service Provider gaat dus over het aanmaken van ESS (Service Specificaties), het aanmaken van berichten en het publiceren van de services. Daarna(ast) geeft het CPA Register de mogelijkheid om aangemaakte services en berichten te beheren.

Gebruik van CPA's

Digikoppeling 1.0 Koppelvlakstandaard definieert twee protocollen (WUS en ebMS) voor de overdracht van gegevens via Digikoppeling. Deze pagina gaat in op het gebruik van een Collaboration Protocol Agreement (CPA) in het geval dat ebMS gebruikt wordt voor de gegevensoverdracht.

Wat is een CPA?

Een CPA is een formeel xml-document om de gebruikte functionele en technische eigenschappen van de ebMS-protocolkarakteristieken vast te leggen. Het is dus een formele beschrijving voor het vastleggen van de gegevensuitwisseling.

De CPA is gestandaardiseerd in [ISO 15000-1: ebXML Collaborative Partner Profile Agreement (afgekort tot ebCPP]. Het ebMS-protocol is gestandaardiseerd in [ISO 15000-2: ebXML Messaging Service Specification (afgekort tot ebMS)].

De eigenschappen van de gegevensoverdracht geven onder andere aan:

• tussen welke partijen er informatie uitgewisseld wordt;
• welke services en actions ('functies') er zijn waar de berichtuitwisseling op wordt gebaseerd;
• hoe certificaten gebruikt worden voor bijvoorbeeld transportbeveiliging, payload encryptie en/of ondertekening van berichten;
• wat de overdrachtskarakteristieken zijn, zoals de intervallen voor hertransmissie als betrouwbare overdracht gewenst is;
• hoe om te gaan met acknowledgments;
• wat de eigenschappen zijn van de transportkanalen.

Waarom wordt er een CPA gebruikt?

Redenen voor het toepassen van een CPA:

• het is een formeel contract tussen twee partijen die op basis van ebMS gegevens willen uitwisselen;
• het automatiseert de e-configuratie van de ebMS-adapter (het inlezen van de CPA volstaat);
• het biedt de zekerheid dat beide partijen dezelfde instellingen gebruiken.

Daarom is de CPA het uitgangspunt voor de specificatie en configuratie van de gegevensuitwisseling tussen twee partijen op Digikoppeling.

Stappenplan algemeen

Het CPA Register slaat gegevens op over de organisatie, de gebruiker, service, certificaten, en digikoppeling. Dit om het de gebruikers makkelijk te maken om op basis van opgeslagen gegevens CPA’s te maken.

Dit hoofdstuk beschrijft de algemene stappen welke zowel door Service providers en door Service requesters doorlopen worden om een CPA te maken.

De Service providers doorlopen naast de stappen in dit hoofdstuk ook de stappen om een berichtspecificatie in het register vast te leggen. Deze stappen worden beschreven in hoofdstuk Stappenplan Service Provider.

Globaal ziet de Providers happy flow als volgt uit: registreren gebruikers, ESS aanmaken, Service publiceren (na controle) en digikoppeling publiceren (na controle).

Globaal ziet de Consumer happy flow als volgt uit: registreren gebruikers, ECS aanmaken en CPA aanmaken.

Stap 1: Aanmelden organisatie

Een gebruiker kan zich pas voor een organisatie registreren, wanneer deze organisatie in het CPA register is ingevoerd. Elke gebruiker wordt dus (gekoppeld aan) één organisatie.

Bij de live gang van het CPA Register zijn de nodige organisaties die gebruik maakten van de vorige CPA creatie voorziening ingevoerd. Indien het registratie proces niet succesvol verloopt, kan het zijn dat de betreffende organisatie niet correct is opgevoerd.

Neem in bovenstaand geval contact op met het Servicecenter van Logius met het verzoek de organisatie gegevens in het CPA Register te controleren. Lever bij het verzoek de onderstaande gegevens aan:

Organisatie gegevens

• Organisatienaam:
• Oin
• Straatnaam
• Huisnummer
• Postcode:
• Plaats
• Telefoon
• Email
• Website
• Email domein

Na bevestiging van het Servicecenter kunnen de gebruikers zich registreren via het CPA Register

Stap 2: Registreren gebruiker

Uitvoering:

Start een browser en ga naar het onderstaande adres:

https://cparegister.nl

Volg de registreren link in de tekst of de via de knop in de balk bovenin beeld.

Voer alle gegevens in en druk op Registreren.

Het systeem zoekt de organisatie op aan de hand van het opgegeven OIN en email domein naam. Bij een match wordt de aanmelder gekoppeld aan die organisatie.

Indien er voor de organisatie nog geen gebruiker bestaat zal de nieuwe gebruiker zelf onderstaande account activatie mail ontvangen.

Wanneer er al een gebruiker geregistreerd is wordt de volgende mail gestuurd:

De bestaande gebruiker ontvangt de volgende mail:

Na het afronden van de bovenstaande stappen is de gebruikersaccount aangemaakt en kan de gebruiker inloggen.

Dashboard / Landingspagina

Na het inloggen wordt het dashboard getoond. Op deze pagina wordt naast de intro tekst ook getoond of CPA’s of certificaten binnenkort verlopen, één maand voor het verlopen wordt van deze CPA’s of certificaten de einddatum in het oranje getoond.

Van reeds verlopen CPA’s of certificaten wordt het einddatum veld rood weergegeven.

E-mail notificaties

Gebruikers van het CPA Register krijgen van specifieke gebeurtenissen e-mail berichten vanuit het CPA register. Via Account / E-mailnotificaties van mijn organisatie kan ingesteld worden welke notificaties naar welke gebruiker verstuurd worden.

Via Extra e-mailadres toevoegen kan een algemeen e-mailadres worden toegevoegd indien er een gezamenlijk mailbox is waar de organisatie gebruik van wil maken voor het ontvangen van notificaties.

Nieuwe CPA

Wanneer een nieuwe CPA in het CPA Register wordt aangemaakt waar uw organisatie bij betrokken is ontvangen alle gebruikers met de vink bij dt veld een email.

Verlopen CPA

Een maand voor het verlopen van een CPA van de eigen organisatie ontvangen gebruikers met deze vink een email met de melding dat een specifieke CPA binnenkort verloopt.

Verlopen certificaten

Een maand voor het verlopen van een aan de eigen organisatie gekoppeld certificaat ontvangen deze gebruikers daarvan een mail notificatie.

Nieuwe gebruiker

Wanneer een nieuwe gebruiker zich registreert voor een organisatie waar reeds gebruikers voorzijn geregistreerd zullen deze gebruikers de activatie mail ontvangen.

Verlopen partner certificaten

Een maand voor het verlopen van een partner certificaat, waar via een CPA een relatie mee is, ontvangen deze gebruikers daarvan een mail notificatie.

Wijziging partner Digikoppeling

Bij het wijzigen van een Digikoppeling profiel, waar via een CPA een relatie mee is, ontvangen deze gebruikers daarvan een mail notificatie.

Wachtwoord wijzigen

In het CPA Register zijn twee mogelijkheden voor het wijzigen van het wachtwoord.

Indien de gebruiker het wachtwoord vergeten is kan via de link Wachtwoord vergeten op de inlogpagina het wachtwoord gereset worden.

Vanuit het CPA Register kan de gebruiker via Account / Wijzig wachtwoord het wachtwoord aanpassen:

Stap 3: Service provider machtigen (optioneel)

Een Service Provider kan als organisatie gemachtigd worden om de werkzaamheden in het register uit te voeren voor een organisatie.

Hiermee krijgen alle geregistreerde medewerkers van de Service provider de rechten om voor de organisatie Digikoppelingen te registreren en CPA’s aan te maken.

Uitvoering:

Log in op de CPA-R door op het tabblad Inloggen te klikken en u aan te melden.

Klik op het tabblad Providers.

Druk op de knop Providers toevoegen/verwijderen.

Met behulp van de >> knoppen worden organisaties toegevoegd en via de << knoppen worden deze weer verwijderd. Na de aanpassing middels de Opslaan knop bevestigen.

Stap 4: CPA manager machtigen (optioneel)

Een niet aan de organisatie gekoppelde persoon (CPA Manager) kan gemachtigd worden om voor de organisatie de digikoppeling te registreren en CPA’s aan te maken. 

Het aanmaken van een account voor de CPA Manager gaat als volgt.

Uitvoering:

Log in op de CPA-R door op het tabblad Inloggen te klikken en u aan te melden.

Klik op het tabblad Account en kies vervolgens voor de optie Accounts voor mijn organisatie.

Druk op de knop Machtig een externe CPA-manager. Vervolgens ziet u onderstaande scherm, waar u de gegevens van de persoon moet invoeren die u machtigt om namens uw aanbieder de routerings- en cpa-gegevens in te voeren en te beheren.

Na het invoeren van de gegevens drukt u op Verzenden.

Indien voor het email adres al een account in het systeem staat dan wordt die persoon gemachtigd, indien er nog geen account bestaat wordt er één aangemaakt.

De persoon ontvangt een email ter informatie dat hij is gemachtigd om als beheerder voor uw organisatie op te treden. 

Stap 5: Digikoppeling registreren

In het Digikoppelingen onderdeel kan de gebruiker digikoppeling profielen registreren. Deze worden later gebruikt in het onderdeel CPA Beheer om CPA’s aan te maken.

Uitvoering:

Log in op de CPA-R door op het tabblad Inloggen te klikken en u aan te melden.

Klik op het tabblad Digikoppelingen.

Het scherm is opgedeeld in drie blokken:

• Overzicht geregistreerde Digikoppelingen
• Overzicht gekoppelde certificaten
• Overzicht aangemaakte CPA’s voor deze Digikoppeling.

Er zijn twee manieren om een Digikoppeling te registreren:

1. Importeren ECS bestand
2. Via invulformulier gegevens opvoeren.

Importeren ECS bestand

Klik op de ECS importeren knop.

Selecteer een bestand en klik op Importeren.

Digikoppeling registreren

Klik vanuit Digikoppeling beheer op de Nieuwe digikoppeling aanmaken knop.

Voer in het invulscherm alle (relevante) velden in:

Let op: De selectie boxen Server-digikoppeling en Gepubliceerd zijn alleen van toepassing voor Service Providers, die een dienst ter beschikking stellen!

Bij het registreren van een test koppeling wordt eerst de vink bij Gebruik voor ontwikkel- en testscenario’s gezet, selecteer daarna de correct OIN suffix. De volgende waarden zijn beschikbaar:

• (geen)
  
  Wanneer er geen aparte identificatie wordt gebruikt
• _O
  
  Voor een ontwikkel systeem koppeling
• _T
  
  Voor een test systeem koppeling
• _A
  
  Voor een acceptatie systeem koppeling
• _OT
  
  Voor een gecombineerde ontwikkel/test systeem koppeling
• _TA
  
  Voor een gecombineerde test/acceptatie systeem koppeling
• _OTA
  
  Voor een gecombineerde ontwikkel/test/acceptatie systeem koppeling.

Certificaten

De publieke delen van de certificaten worden gekoppeld aan het digikoppeling profiel. 

Voor een Digikoppeling profiel kan worden aangegeven of een CPA wissel nodig is bij het verlopen van certificaten. Indien gebruik gemaakt wordt van SSL offloading kan het voorkomen dat dit niet noodzakelijk is.

Let op: Er wordt niet gewerkt met keyinfo xml bestanden!

Afhankelijk van de dienst, waarop wordt aangesloten, worden de gekoppelde certificaten wel of niet verwerkt in de uiteindelijke CPA.

Digikoppeling details

Beschikbare digikoppeling profielen kunnen via de Bekijk link in het overzicht geopend worden.

Onder de kerngegevens van het profiel worden de certificaten getoond:

Onderaan de pagina wordt een overzicht getoond van de CPA’s die met dit profiel aangemaakt zijn:

Na het doorvoeren van een wijziging aan het profiel, bijvoorbeeld het vervangen van certificaten of de url kunnen alle betreffende CPA’s vanaf deze pagina opnieuw aangemaakt worden.

Let op: Wanneer er geen vakje voor een CPA staat dan kan deze niet verlengd worden, dit kan zijn doordat de berichtspecificatie ingetrokken is. In die situatie wordt er een envelope ikoon naast de specificatienaam geplaats. Via die link kan men contact opnemen met de beheerder van de specificatie.

Certificaat overzicht

Na het importeren of aanmaken van digikoppeling profielen worden de gebruikte certificaten in het Certificaat overzicht geplaatst op de hoofdpagina van Digikoppeling beheer.

In het overzicht hierboven staat een voorbeeld van een overzicht met een verlopen certificaat. 

Het CPA Register stuurt een email naar de geregistreerde gebruikers van een organisatie wanneer een certificaat binnen 4 weken verloopt.

Stap 6: CPA Aanmaken

Via CPA’s kan een gebruiker een CPA aanmaken en zijn reeds aangemaakte CPA’s downloaden.

Uitvoering:

Druk op de knop Nieuwe CPA aanvragen in het CPA Beheer overzicht scherm.

Voer de volgende velden in:

1. Selecteer de specificatie
   
   Zoeken op specificatie kan via de knop ‘Specificatie filteren op publicerende organisatie’
2. Selecteer het eigen digikoppeling profiel
3. Selecteer de client/consumer rol
   
   De rollen zijn vastgelegd in de berichtspecificatie die door de service provider is vastgesteld. Indien er vragen zijn over de te gebruiken rol kunt u contact opnemen met de service provider.
4. Selecteer de digikoppeling van de service provider
5. Selecteer de rol van de service provider
   
   Wanneer de specificatie correct is ingevoerd zal de rol al een default waarde hebben.
6. De CPA ID is optioneel, indien niet ingevuld wordt een standaard CPA ID aangemaakt.

In het CPA Overzicht scherm wordt de status getoond, via de Ververs status knop wordt de status opgehaald.

Nadat de CPA is aangemaakt kan deze via de bestandsnaam, of de Download link gedownload worden.

De Service Provider ontvangt een email zodra er een nieuwe CPA is aangemaakt op basis van hun service.

Het CPA Register stuurt een email naar de geregistreerde gebruikers van een organisatie wanneer een cpa binnen 4 weken verloopt.

CPA Detail pagina

Klik voor de CPA Detailpagina vanuit het CPA Overzicht op de link Meer info.

CPA Detail gegevens:

Vanaf de detail pagina zijn zowel voor de service provider en de consumer de certificaten te downloaden.

Stappenplan Service Provider

De service provider zal de service specificeren waarmee op een later tijdstip een CPA gemaakt kan worden. Dit hoofdstuk beschrijft welke informatie nodig is om een specificatie samen te stellen en hoe deze specificatie ingevoerd moet worden.

Introductie

Via het onderdeel Service beheer kan de service provider de Digikoppeling Servicespecificatie(s) aanmaken en beheren.

De service provider heeft de verantwoordelijkheid om de ebMS-berichtenuitwisseling te specificeren. Deze specificatie wordt vastgelegd in een Digikoppeling-ebMS Servicespecificatie en bevat de volgende onderdelen:

• De service Identificerende naam (ID): een unieke naam van de service of Digikoppeling, op deze pagina aangeduid met ID, die de service requester (of consumer) zal gebruiken om een CPA te maken met de service provider.
• Digikoppeling-ebMS Servicespecificatie moet gepubliceerd worden.
• Daarnaast kan Digikoppeling-ebMS Servicespecificatie ingevoerd worden in het CPA Register, zodat service requesters op een eenvoudige wijze een CPA kunnen maken. De naam waaronder Digikoppeling-ebMS Servicespecificatie opgeslagen wordt in het CPA Register zal aangegeven moeten worden in het Digikoppeling Service Register.
• De berichttypes (messageTypes): de definities van de berichten zijn vastgelegd in een bepaalde namespace en bijbehorende xsd.
• De berichtenspecificatie (messages): de berichten die uitgewisseld worden tussen een SP en SR, en welk Digikoppeling-profiel hierbij gehanteerd wordt.
• De parameterspecificatie (params) waarmee aangegeven wordt welke gegevens specifiek voor de organisatie zijn en opgegeven moeten worden door de SP en de SR.
• De parameterwaarden (parameters) van de betreffende SP of SR (één van beide). Het huidige model gaat er vanuit dat er één partij is waarvoor de gegevens al kunnen worden aangeleverd en N partijen waarvoor dit nog niet het geval is (het 1-op-N-model).

De service provider kan op twee manieren de Digikoppeling-ebMS Servicespecificatie op het CPA Register plaatsen:

1. Door een bestaand ESS bestand te importeren
2. Via de wizzard op het CPA Register.

In sectie 5.2 wordt de invulling van een specificatie toegelicht.

ESS achtergrond

De service die wordt aangeboden door de service provider (en wordt afgenomen door de service requester) moet een unieke naam hebben.

Deze naam wordt hier aangeduid met ‘ID’. De naam wordt ook gebruikt om informatie te vinden over de service via het Digikoppeling Service Register.

De ID wordt gebruikt bij het maken van de CPA. Kies in het CPA register bij het onderdeel Service beheer voor

Het is de verantwoordelijkheid van de service provider om een unieke en betekenisvolle naam (‘ID’) te geven aan de service.

Naamgevingsconventie

De opbouw van de naam is gebaseerd op een hiërarchische structuur van sub-namen (alleen letters en/of cijfers), gescheiden door een punt. Laat de naam beginnen met een unieke naam van de organisatie. De naam mag geen spaties of speciale tekens bevatten.

TIP 1: laat de ID zoveel mogelijk overeenkomen met de service naam in Digikoppeling-ebMS Servicespecificatie.

TIP 2: vergeet niet om bij de publicatie van Digikoppeling-ebMS Servicespecificatie in het Digikoppeling Service Register de ID te noemen waarmee de specificatie is opgeslagen in de CPA Creatievoorziening.

Voorbeeld

Een service van Digikoppeling is de ebMS Compliancevoorziening. De ID kan dan zijn: Digikoppeling.CVebMS. Omdat een versienummer van belang is wordt de ID: Digikoppeling.CVebMS.1.0

Importeren ESS in het CPA Register

Na het aanmaken van de ESS wordt deze geïmporteerd in het CPA Register.

Uitvoering:

Middels de knop ESS importeren in het onderdeel Service beheer kan de service provider de aangemaakte ESS importeren.

De provider selecteerd het ESS bestand m.b.v. de knop Bestand kiezen en klikt daarna op Importeren.

Onderstaande melding geeft aan dat de specificatie succesvol geïmporteerd is:

Aanmaken Specificatie

Via het onderdeel Specificaties kan de service provider een specificatie via het portaal invoeren.

Stap 1: Aanmaken specificatie

De provider gebruikt de knop Specificatie aanmaken in het onderdeel Service beheer om het proces te starten.

Voer de naam in en optioneel een verkorte naam die gebruikt wordt wanneer de gebruiker kiest voor de standaard CPAID bij het genereren van een CPA.

De specificatie is nu aangemaakt en kan gevuld worden. Klik op de specificatie naam om verder te gaan.

Stap 2: Aanmaken rollen

Klik op beheer rollen en services bij de net aangemaakte specificatie.

Maak via de knop Rol aanmaken de rollen van de specificatie aan.

Geef met een vink aan of de rol een server of client rol is.

Stap 3: Aanmaken service

Maak de service(s) aan:

Stap 4: Maak de berichten aan

Maak via de knop beheer berichten de berichten aan.

Kies voor Bericht aanmaken en voer de berichtgegevens in:

Selecteer een passend berichtprofiel, indien de default instellingen niet voldoen, gebruik dan Pas retry-instellingen aan om dit aan te passen. Bevestig het bericht met de knop Opslaan.

De specificatie is nu aangemaakt.

Stap 5: Server digikoppeling koppelen (Optioneel)

Het is mogelijk om een specificatie expliciet te koppelen aan specifieke server Digikoppelingen. Op deze manier wordt voorkomen dat een consumer bij het aanmaken van een CPA een verkeerde server Digikoppeling selecteert.

Klik vanuit Specificaties op een specificatie:

Kies voor Digikoppeling koppelen en selecteer de gewenste Digikoppeling.

Herhaal deze stap voor alle gewenste server digikoppelingen, bijv Test, Acceptatie, Productie etc.

Stap 6: Publiceren

De bericht specificatie is pas voor derde partijen zicht in het CPA Register wanneer de service provider de service publiceert.

Klik vanuit Specificaties op een specificatie:

Gebruik de knop Specificatie publiceren. De specificatie is nu door alle partijen te gebruiken om een CPA mee aan te maken.

Genereer-link opvragen

Het CPA Register kan een link genereren naar een CPA Aanvraag pagina voor gebruik in de eigen documentatie van de Service Provider. Deze link selecteert de correcte specificatie en server Digikoppeling voor de aansluitende consumer.

Uitvoering:

Klik vanuit Specificaties op een specificatie en kies voor Genereer-link opvragen:

Selecteer de Server digikoppeling en kopieer de link bij url.

Exporteren ESS

Berichtspecificaties kunnen in ESS formaat geëxporteerd worden uit het CPA Register.

Let op: Een ESS bestand kan alleen worden geëxporteerd wanneer een server digikoppeling profiel is aangemaakt!

Ga naar de specificaties pagina:

Klik op de berichtspecificatie:

Klik nu op de service in het blok Services:

Gebruik nu de knop ESS exporteren:

Selecteer de server koppeling, koppel de rollen en druk op ESS exporteren.

Bulk CPA Aanvraag

Na een wijziging in een digikoppeling profiel, bijvoorbeeld certificaat of url is het mogelijk om middels één actie alle CPA’s die gebruik maken van die Digikoppeling adapter opnieuw te genereren.

Het resultaat is een download link die verwijst naar een zip bestand met daarin alle gegenereerde CPA’s.

Ga naar Digikoppelingen en selecteer de te wijzigen Digikoppeling, voer de wijziging door en ga naar de detail pagina van de Digikoppeling.

Onderaan de pagina staat een sectie getiteld CPA’s

E-mail template

Alle partijen die bij deze Digikoppeling wijziging betrokken zijn kunnen vanuit het CPA Register geïnformeerd worden met een mail die zelf kan worden aangepast.

Let op: Alleen gebruikers van de betrokken partijen die een e-mail notificatie ontvangen bij het aanmaken van een nieuwe CPA krijgen deze mail.

Zet een vink bij Stuur e-mail naar alle betrokken beheerders na opnieuw genereren van CPA's. De standaard tekst wordt getoond deze kan naar wens worden aangepast.

Na het genereren van de CPA’s wordt een mail gestuurd met een link naar het bulkbestand waar alle CPA’s inzitten.

Gebruikers met een CPA tussen hun eigen en deze Digikoppeling krijgen een mail met daarin de melding uit de template en zij zullen de CPA zelf moeten downloaden.

CPA selectie

Door middel van de selectiebox in de titel regel kunnen alle tegelijk CPA’s geselecteerd worden of via de afzonderlijke selectie boxen per CPA.

Let op: CPA’s waarbij beide partijen hebben aangegeven dat zij geen nieuwe CPA nodig hebben bij een certificaatwissel zijn standaard niet aangevinkt.

API

Het CPA Register beschikt over een REST API interface waarmee Service Providers bepaalde handelingen geautomatiseerd kunnen uitvoeren. Dit hoofdstuk beschrijft hoe een Service Provider deze functionaliteit kan gebruiken.

Toegang/API Keys

Het CPA register maakt gebruik van API keys voor de ontsluiting van de API. Een als ontwikkelaar aangemelde gebruiker kan een API key generen.

Ga naar Account / Accounts voor mijn organisatie en zet een vink in de Ontwikkelaar kolom voor de betreffende gebruiker. De gebruiker krijgt nu een Ontwikkelaar menu in de menu balk.

Via de API kunnen alleen die objecten beheerd worden die door de organisatie ook beheerd kunnen worden. M.a.w. de API key bepaalt de scope van de toegang.

Een key aanvragen gaat via het Ontwikkelaar / API Keys menu.

API keys moeten worden meegestuurd in de Authorization HTTP-header als volgt:

Authorization: Api-Key XWo73KiJ.iG3qBGlpzRY7uQvLSJqqCdsIcsyApLrQ

Bij het aanmaken van een API key wordt de geheime sleutel voor die key éénmalig getoond.

Documentatie

De volledige documentatie van de API functionaliteit is via Ontwikkelaar / Documentatie Beschikbaar. Via deze zelfde weg kan de API getest worden.

Interfaces

Hieronder wordt alleen een beknopt overzicht getoond van de API interface.

Het OAS bestand is via de volgende link beschikbaar: https://cparegister.nl/api/v1

De volgende functies/acties zijn beschikbaar:

Digikoppelingen

GET /api/v1/digikoppelingen Lijst van digikoppelingen

POST /api/v1/digikoppelingen Maak een nieuwe digikoppeling aan

GET /api/v1/digikoppelingen/{id} Vraag details van een enkele digikoppeling op

PUT /api/v1/digikoppelingen/{id} Werk een bestaande digikoppeling bij

PATCH /api/v1/digikoppelingen/{id} Werk een bestaande digikoppeling bij

DELETE /api/v1/digikoppelingen/{id} Verwijder een digikoppeling

Organisaties

GET /api/v1/organisaties Lijst van organisaties

GET /api/v1/organisaties/{id} Vraag details van een enkele organisatie op

Specificaties

GET /api/v1/specificaties Lijst van berichtspecificaties

GET /api/v1/specificaties/{id} Vraag details van een enkele specificatie op

CPA-aanvragen

GET /api/v1/cpa_aanvragen Lijst van CPA-aanvragen

POST /api/v1/cpa_aanvragen Vraag een nieuwe CPA aan

GET /api/v1/cpa_aanvragen/{id} Vraag details van een enkele CPA-aanvraag op.

CPA's

GET /api/v1/cpas/{id} Vraag de inhoud van een enkele CPA op

Referenties

[Digikoppeling-1.0] Digikoppeling Koppelvlakstandaard ebMS, Digikoppeling 

[Digikoppeling-BPE] Digikoppeling Best Practices ebMS

[Digikoppeling-CPB] Digikoppeling CPA Creatie Procesbeschrijving

Bijlage 1 - Parameterlijst

Deze bijlage specificeert de parameters waarmee aangegeven kan worden welke gegevens nog opgegeven moeten worden door een organisatie. Zie paragraaf 5.2.3 voor het gebruik van deze parameters.

Verplichte parameters

Parameter	Betekenis	Default	Voorkomen
PartyName	De naam van de partij die een bepaalde rol inneemt.	Niet van toepassing.	Verplicht
PartyId	De logische identificatie van de partij die een bepaalde rol inneemt.	De OIN van het cliëntcertificaat van de organisatie. Afwijkingen zijn toegestaan indien de organisatie een ander identificatieschema heeft waarmee ze zich wil identificeren op Digikoppeling.	Er moet óf een PartyId óf een PartyIdList gedefinieerd zijn (niet beide).
PartyIdList	Een lijst met logische identificaties van de partijen die een bepaalde rol innemen.Deze PartyId’s zijn verbonden aan één en dezelfde PartyName.	Zie PartyId.	Er moet OF een PartyId OF een PartyIdList gedefinieerd zijn (niet beide).
EndpointUri	De HTTPS (dus met TLS/SSL) transport-url van de ebMS -adapter van de organisatie. Noot: voor testdoeleinden kan HTTP, dus zonder SSL, gebruikt worden. Hiervoor moet de parameter HTTPEndpointUri gebruikt worden.	Niet van toepassing.	Verplicht
ClientCert	Het publieke deel van het client certificaat van de organisatie.	Niet van toepassing.	Verplicht. Het gegeven wordt opgegeven in de vorm van een KeyInfo structuur.
ServerCert	Het publieke deel van het servercertificaat van de server van de ebMS-adapter van de organisatie.	Niet van toepassing.	Verplicht. Het gegeven wordt opgegeven in de vorm van een KeyInfo-structuur.

Optionele parameters

Parameter	Betekenis	Default	Voorkomen
PartyIdType	De typering van de PartyId (of PartyIdList elementen) van de logische identificatie.	De default waarde is urn:osb:bin en typeert het gebruik van een OIN als PartyId. Indien een andere identificatie schema gehanteerd wordt voor de PartyId, zal de typering gebruikt moeten worden die daarbij past.	Optioneel indien gebruik gemaakt wordt van een OIN, verplicht in de overige gevallen.
PartyRef	Een referentie naar een webpagina of website met informatie over de betreffende service van de organisatie. De referentie is bedoeld om gebruikt te worden door personen.	Leeg.	Optioneel.
Retries	De Retries geven aan hoe vaak een poging gedaan moet worden om een bericht te versturen.	De default waarde is driemaal.	Optioneel. Mogelijke waardes: integer groter of gelijk 0.
RetryInterval	Het RetryInterval geeft aan hoe lang er gewacht wordt voordat er een nieuwe poging gedaan wordt om een bericht opnieuw te versturen.	De default waarde is acht uur.	Optioneel. Mogelijke waarde: zie ‘duration’ in “XML Schema[XMLSCHEMA-2]”.
PersistDuration	De PersistDuration geeft aan hoe lang berichten bewaard moeten worden door de ebMS-adapter. Het is een minimum periode. Door deze periode langer te maken dan de periode van RetryInterval x Retries is de beheerder van de ebMS adapter in staat om berichten die uiteindelijk niet overgedragen konden worden binnen de gestelde termijn, toch opnieuw te versturen. Implementatie in CPA Register: PersistDuration = RetryInterval x (Retries + 1)	De default waarde is acht uur.	Optioneel. Mogelijke waarde: zie ‘duration’ in “XML Schema[XMLSCHEMA-2]”.
MessageOrder	De MessageOrder geeft aan of berichten met eenzelfde ConversationId in volgorde moeten worden afgeleverd.	Default staat de MessageOrder uit ('not guaranteerd'). Indien MessageOrder gewenst is, zal deze parameter van de aangegeven waarde moeten worden voorzien.	Optioneel. Mogelijke waarde: Guaranteed.