Gebruikershandleiding Digikoppeling Serviceregister

Gebruikershandleiding Digikoppeling Serviceregister Versie 1.3

Datum

6 februari 2014

| Gebruikershandleiding Digikoppeling Serviceregister| 6 februari 2014

Colofon

Projectnaam Versienummer Organisatie

Digikoppeling Definitief Servicecentrum Logius Postbus 96810 | 2509 JE Den Haag T 0900 555 4555 [email protected]

Bijlage(n)

0

Pagina 2 van 39


Inhoud

Colofon ................................................................................................................... 2 Inhoud .................................................................................................................... 3 Inleiding ................................................................................................................ 5 1.1 Over Digikoppeling ................................................................................ 5 1.1.1 Leidend principe: één stekker ................................................... 5 1.1.2 Koppelvlak en koppelvlakstandaard ........................................ 5 1.2 Over het Serviceregister ..................................................................... 6 1.2.1 Services weergegeven als Business Service ........................ 6 1.2.2 Technische documentatie voor service requester .............. 6 1.2.3 Toegang tot het Register ............................................................. 6 1.3 Leeswijzer ................................................................................................. 6 1.3.1 Rollen .................................................................................................. 6 1.4 2

Aanmelden .................................................................................................... 8 2.1

3

4

Terminologie ............................................................................................ 7

Aanmelden bij het Serviceregister (inloggen) ............................ 8

Organisatie- en contactpersoongegevens beheren............ 10 3.1

Beheer van organisatiegegevens ................................................... 10

3.2

Beheer van contactpersoongegevens .......................................... 11

3.3

Koppelen van contactpersonen aan organisaties .................... 11

Service publiceren .................................................................................. 12 4.1

Business Service aanmaken ............................................................ 12

4.2 Implementatie toevoegen ................................................................ 16 4.2.1 SOAP Service (Digikoppeling WUS) ....................................... 17 4.2.2 Digikoppeling ebMS Service ..................................................... 20

5

4.3

Documentatie toevoegen .................................................................. 22

4.4

Certificaten toevoegen ....................................................................... 24

Services zoeken ....................................................................................... 26 5.1 Zoeken op Business Service ............................................................ 26 5.1.1 Resultaat sorteren ........................................................................ 27 5.1.2 Resultaat verfijnen met zoekfilter .......................................... 27 5.1.3 Aantal getoonde services aanpassen .................................... 28 5.1.4 Door het overzicht navigeren .................................................. 28 5.2

Zoeken op vrije tekst ......................................................................... 29

5.3

Zoeken op Implementatie ................................................................ 30 Pagina 3 van 39


6

7

Bericht 'broadcasting': generieke servicedefinities ........... 32 6.1

Generieke service aanmaken .......................................................... 33

6.2

Implementeren op basis van generieke service ...................... 34

6.3

Procedurele aspecten ......................................................................... 35

Gebruiksovereenkomsten .................................................................. 36 7.1

Service zoeken...................................................................................... 36

7.2

Consumption Request maken ......................................................... 36

7.3

Consumption Request accepteren of verwerpen ..................... 37

7.4

Servicegegevens gebruiken ............................................................. 39

Pagina 4 van 39


Inleiding

1.1

Over Digikoppeling Het Serviceregister is een onderdeel van de Digikoppeling. Het project Digikoppeling definieert koppelvlakken om de uitwisseling van berichten tussen overheidsorganisaties — service aanbieders (service providers) en service afnemers (service requesters) — te standaardiseren. Deze uitwisseling valt uiteen in drie lagen: Inhoud Afspraken over de inhoud van het uit te wisselen bericht: structuur, semantiek en waardebereik. Logistiek Afspraken over transportprotocol (HTTP), messaging (SOAP), beveiliging (authenticatie en encryptie) en betrouwbaarheid. Transport Het daadwerkelijke transport van het bericht. Digikoppeling richt zich uitsluitend op de logistieke laag. De afspraken op deze laag zijn vastgelegd in ‘koppelvlakstandaarden’ en andere voorzieningen.

1.1.1

Leidend principe: één stekker Overheidsorganisaties hebben aangegeven op een uniforme manier te willen aansluiten op Digikoppeling: één stekker. Digikoppeling biedt dit ene ‘koppelvlak’, waarmee alle interactie tussen organisaties onderling, via Digikoppeling, wordt afgehandeld. Koppelvlakstandaarden moeten zorgen voor maximale interoperabiliteit, bij minimale ontwikkelinspanning. Daarom is gekozen voor bewezen, interoperabele internationale standaarden: de ebXML/ebMS- en WUS-families (WSDL, UDDI en SOAP) inclusief verwante standaarden. Organisaties die weinig expertise hebben op het gebied van ebXML en WUS kunnen berichten uitwisselen via WUSlite en JMS (Java Message Service) via Digikoppeling Gateway (lees hier meer over in Digikoppeling Gateway-documentatie). Dit koppelvlak is bovendien beschikbaar in twee varianten: WUS-lite en JMS (Java Message Service).

1.1.2

Koppelvlak en koppelvlakstandaard Een koppelvlak is een interface die gegevensuitwisseling verzorgt. Werken met vergaande, vaste standaarden is essentieel: het vergemakkelijkt implementatie. Ook wordt het mogelijk verschillende soorten berichten te versturen met een grote mate van interoperabiliteit. In de standaard zijn immers afspraken over inhoud gemaakt.

Pagina 5 van 39


Kant-en-klare software Eén van de belangrijkste eisen van de overheid voor inrichting van generieke voorzieningen, is dat er niet veel maatwerk ontwikkeld hoeft te worden. Er moet kant-en-klare commercieel of open geleverde software gebruikt worden. Voor Digikoppeling betekent dit dat geen software voor adapters wordt ontwikkeld, maar dat gekozen is voor internationaal (de jure of de facto) vastgelegde standaarden, die ‘alle’ leveranciers interoperabel hebben geïmplementeerd 1.2

Over het Serviceregister Het Serviceregister is een catalogus van services die organisaties aanbieden via Digikoppeling. Het gaat om zowel beschikbare services als services die nog in ontwikkeling zijn. Deze services worden binnen de eoverheid gebruikt om op een gestandaardiseerde manier gegevens uit te wisselen. Overheidsorganisaties kunnen services in het Register publiceren, inclusief alle informatie die potentiële afnemers van zo’n service nodig hebben om die service te gebruiken.

1.2.1

Services weergegeven als Business Service Het Serviceregister geeft services primair weer als Business Service. Met andere woorden, van services wordt in eerste instantie functionele informatie aangeboden, geschreven in businesstermen. Denk aan:  Aanbiederinformatie  Procesbeschrijvingen Binnen welk proces speelt de service een rol, of welk proces ‘realiseert’ de service?  Functioneel ontwerp, functionele specificaties  Afnamecondities  Enzovoort

1.2.2

Technische documentatie voor service requester Afnemers (service requesters) van een service, die via Digikoppeling wordt aangeboden, hebben verschillende gegevens nodig om zo’n service te kunnen gebruiken. Voordat deze service requester berichten naar een Digikoppeling -service kan versturen, moet hij zelf software realiseren of configureren. De informatie op basis waarvan de service requester zijn software inricht, staat ook in het Serviceregister. Denk aan:  Technische contractbeschrijvingen (WSDL, ebMS Service Specificatie)  Berichtdefinities (XSD’s)  Certificaatgegevens (public key gegevens)

1.2.3

Toegang tot het Register Het Serviceregister is alleen toegankelijk voor geregistreerde gebruikers. Internetadres en inloggegevens krijgt u van de centrale beheerder van het Register. Contactinformatie vindt u achter in dit document.

1.3

Leeswijzer

1.3.1

Rollen Dit document is bedoeld voor verschillende gebruikersrollen:  Provider  Consumer Provider Organisaties die services aanbieden, noemen we service providers. Medewerkers van die organisaties, die verantwoordelijk zijn voor het Pagina 6 van 39


invoeren en up-to-date houden van gegevens, zijn (data) providers. Zij kunnen uitsluitend gegevens invoeren en wijzigingen doorvoeren, van de services van hun eigen organisatie. Consumer Organisaties die services willen afnemen, noemen we service requesters. Medewerkers van die organisaties kunnen in het Serviceregister zoeken naar services. Hen noemen we consumers; ze hebben toegang tot servicegegevens, maar kunnen deze gegevens niet wijzigen. 1.4

Terminologie Lees voor uitleg van termen die binnen het Digikoppeling -domein gebruikt worden in de ‘Digikoppeling Glossary’ (zie www.publicatieplein.nl ).

Pagina 7 van 39


2

Aanmelden

Het Serviceregister is bereikbaar via internet. Alleen geregistreerde gebruikers hebben toegang tot het register. Meld u aan via www.logius.nl/digikoppeling. De beheerder van Digikoppeling verstrekt u de benodigde gegevens. 2.1

Aanmelden bij het Serviceregister (inloggen) Ga naar het webadres dat u van Digikoppeling-beheerder hebt gekregen.

Figuur 2-a Aanmelden bij het Serviceregister Vul uw gebruikersnaam en wachtwoord in, in de daarvoor bestemde velden, en klik op ‘Sign In’. Vervolgens verschijnt het ‘dashboard’. Dit ziet er bijvoorbeeld als volgt uit:

Figuur 2-b Het ‘dashboard’ van het register Uw eigen dashboard kan andere elementen en informatie bevatten dan in dit voorbeeld weergegeven.

Pagina 8 van 39


Foutmelding Zijn uw gegevens fout, dan krijgt u een foutmelding: “User authentication failed”. Voer uw gegevens opnieuw in. Krijgt u de foutmelding opnieuw, neem dan contact op met Digikoppeling-beheerder. Contactgegevens vindt u elders in dit document.

Pagina 9 van 39


3

Organisatie- en contactpersoongegevens beheren

Het Serviceregister bevat naast servicegegevens ook gegevens van organisaties en contactpersonen van die organisaties. 3.1

Beheer van organisatiegegevens Uw organisatiegegevens zijn initieel door de centrale beheerder van het Serviceregister ingevoerd. De gegevens zijn vervolgens door de organisatie zelf te wijzigen. Een organisatiegebruiker dient hiertoe echter ingelogd te zijn als 'organisatie administrator'.

Organisatiegegevens zijn te wijzigen door een gebruiker in de rol van 'organisatie administrator'. Het is aan te bevelen de organisatiegegevens direct op juisth eid te controleren op het moment dat voor de eerste keer als 'org.admin' wordt ingelogd. Onjuistheden kunnen worden doorgegeven aan de centrale beheerder van het Serviceregister. Om toegang te krijgen tot organisatiegegevens kunt u de volgende stappen doorlopen:

Figuur 3-a Toegang krijgen tot organisatiegegevens Ga naar de 'Tools'-tab. Organisatiegegevens zijn toegankelijk door eerst op 'Contacts' te klikken. Hierdoor worden de opties 'Organisaties' en 'Contactpersonen' getoond. Klik op 'Organisaties'. Hierdoor wordt het zoekscherm voor 'Organisaties' geopend. Via de 'Find'-knop is desgewenst een zoekfilter in te stellen (zie voor een uitgebreide beschrijving van zoekfunctionaliteit paragraaf 5.1). Pagina 10 van 39


Klik op de organisatienaam. Hierdoor worden de details van de organisatie getoond. Indien u als 'organisatie administrator' bent ingelogd, kunt u door op de 'Edit'-knop te klikken de organisatiegegevens wijzigen. Opmerking: voor overige gebruikersrollen resulteert het klikken van de 'Edit'-knop in een scherm waarmee relaties tussen de organisatie en andere elementen in de catalogus (bijvoorbeeld documenten en contactpersonen) kunnen worden gelegd. 3.2

Beheer van contactpersoongegevens Contactpersonen kunnen uitsluitend hun eigen contactpersoongegevens wijzigen. Toegang tot contactpersoongegevens verloopt op dezelfde manier als hierboven beschreven voor organisatiegegevens, alleen wordt nu onder 'Contacts' gekozen voor 'Contactpersonen'.

3.3

Koppelen van contactpersonen aan organisaties Contactpersonen kunnen worden gekoppeld aan de organisatie waarvoor zij werkzaam zijn (of waarvoor zij als contactpersoon acteren). Dit kan worden gedaan op twee manieren: 1.

organisatie aan contactpersoon koppelen (ingang is contactpersoon);

2.

contactpersoon aan organisatie koppelen (ingang is organisatie)

In beide gevallen kan de koppeling worden gerealiseerd door op de knop 'Add Relationship' te klikken (onderaan het betreffende scherm).

Figuur 3-b Contactpersoon toevoegen Selecteer in het 'Add Relationship'-scherm de optie 'Contactpersonen van Organisatie'. Opmerking: deze optie geldt voor zowel Organisaties als voor Contactpersonen. Klik op 'Next'. Nu worden alle 'Contacts' getoond, dus zowel Organisaties als Contactpersonen. Selecteer de juiste 'Contact' door deze aan te vinken en klik op 'Next'. Klik vervolgens op 'Finish'. Persoon of organisatie is toegevoegd.

Pagina 11 van 39


4

Service publiceren

Organisaties kunnen gegevens over hun Bedrijfsservice via het Serviceregister publiceren voor potentiële afnemers. Dit gebeurt in vier stappen: 3.

Business Service aanmaken

4.

Service-implementatie toevoegen (indien aanwezig)

5.

Documentatie toevoegen (indien aanwezig)

6.

Gegevens gepubliceerd door service provider

Het publiceren van servicegegevens wordt gedaan door gebruikers die binnen het register ‘service providers’ worden genoemd. In dit hoofdstuk gaan we ervan uit dat de gebruiker is ingelogd als service provider. Dit betekent dat u rechtsboven in het scherm ‘Service Provider’ ziet staan en dat u de tab ‘Services’ ziet.

Figuur 4-a De plaats van de 'Services'-tab

Verschillende ‘views’

Figuur 4-b Keuzemogelijkheden voor de 'view' op gegevens Gegevens in het Serviceregister kunt u op meerdere manieren bekijken. Deze verschillende weergaven noemen we ‘views’. Afhankelijk van de view die u kiest, ziet u meer of minder gegevens en knoppen. U kunt de view aanpassen met het 'Views'-menu. In deze handleiding gaan we standaard uit van de view 'Services'. Waar een andere view van belang is, geven we dit expliciet aan. 4.1

Business Service aanmaken Klik op de tab ‘Services’ voor alle informatie over services en eventuele servicecontracten. Het volgende scherm verschijnt:

Pagina 12 van 39


Figuur 4-c Plaats van 'New Service' in het menu Klik in het blok ‘New’, links in het scherm, op ‘Service’ om een nieuwe Business Service aan te maken. Het volgende scherm verschijnt:

Figuur 4-d Publiceren van een Business Service Vul in de verschillende velden gegevens in conform onderstaand overzicht:

Pagina 13 van 39


Veld

Voorwaarde(n), formaat, opmerkingen

Naam

Verplicht; zie naamgevingsconventies hieronder

Omschrijving

De eerste 30 karakters van de omschrijving zijn zichtbaar in het overzichtsscherm, waarin beschikbare services worden getoond. Op basis van deze omschrijving is de service mede te identificeren. Gebruik daarom een korte, eenduidige omschrijving.

Lifecycle Stage

Standaard eerste fase: ‘in ontwikkeling’

Versienummer

Numerieke versieaanduiding

Enable Consumption Vink alleen aan als de service in Lifecycle Stage ‘preproductie’ of ‘productie’ is. Hiermee geeft u aan dat de service feitelijk in staat is om berichten te verwerken. Zoektermen

Kommagescheiden lijst van zoektermen. Op basis van deze termen kan de gebruiker snel een service vinden via 'zoeken op vrije tekst'. Neem hierin minimaal op:

•De naam van de organisatie die de service aanbiedt. •Overige delen van de naam van de service (uitgeschreven, niet afgekort).

•Basisregistratie, gegevensbron of bijvoorbeeld wetgeving waar de service betrekking op heeft.

•Onderscheid: is het een generieke service? (zie

6.Generieke

services) Associated Approval Vooralsnog niet gebruikt. Provider

Kies uw eigen organisatie uit de lijst. De lijst verschijnt als u op ‘Provider’ klikt. U ziet in de lijst ook gebruikersgegevens, maar kies alleen uw eigen organisatie.

Service wordt

Datum; alleen invullen als de service op de nominatie staat

verwijderd op

om verwijderd te worden.

Naamgevingsconventies Business Services in het Serviceregister kunnen beter gevonden worden als voor alle services een uniforme naamgeving wordt gehanteerd. Neem daarom de volgende elementen op in de servicenaam (niet alle elementen zijn verplicht):  Functie/taak van de service, bijvoorbeeld: ‘zoek gegevens’; ‘valideer gegegevens’; ‘muteer gegevens’; ‘registreer’.  (Bedrijfs-)object waarop de functie wordt uitgevoerd.  Aanbiederidentificatie (organisatie of subdomein) Gebruik hiervoor de afkorting waarmee uw organisatie uniek wordt geïdentificeerd.  Wet waarvoor de service functionaliteit biedt.

Pagina 14 van 39






Groep met gerelateerde services Is de service onderdeel van een groep services die samen een functionele eenheid vormen? Versienummer.

Neem minimaal de volgende elementen op in de naam: < aanbiederorgAfkorting >_< functie/taak >_< versieNr > Voorbeeld: ‘ICTU_ Digikoppeling CompliancyCheck_v1.0’. Als best practice voor volgorde geldt: < orgAfk >_< object >_< functie/taak >_< wet-ID >_< groepID >_< versieNr > Klik op ‘Save’ om de gegevens op te slaan in het DIGIKOPPELING Service Register. Vervolgens kunt u documenten, implementaties en SLO’s (Service Level Objectives) aan de Business Service toevoegen. Meer hierover leest u in de volgende paragrafen. Permissies van de Business Service aanpassen: Degene die een Business Service invoert, die is in het Serviceregister automatisch ‘eigenaar’ van de betreffende gegevens. Dit betekent dat alleen die persoon de gegevens mag wijzigen; deze persoon beschikt immers over de juiste ‘permissies’. Voor het Serviceregister is echter afgesproken dat alle gebruikers binnen een organisatie die als service provider kunnen inloggen, deze servicegegevens moeten kunnen wijzigen. Hiervoor moet u de permissies voor de Business Service aanpassen. Dit doet u als volgt:

Figuur 4-e Toegang krijgen tot 'access rights' op een Business Service 7.

Kies de juiste Business Service. Klik onder ‘Views’ op ‘Access rights’. In het scherm dat verschijnt, ziet u welke groepen welke rechten hebben. Standaard hebben alle geregistreerde gebruikers leesrechten (‘read permission’); de ‘eigenaar’ heeft schrijfrechten (‘write permission’);

Pagina 15 van 39


8.

Klik op ‘Edit’. In het volgende scherm kent u schrijfrechten toe aan de juiste groep. Kies hiervoor eerst de groep: vul de naam van de groep (volgens formaat -Provider) in in het 'Search For'-veld en klik op ‘Go’. De Provider-groep van de organisatie verschijnt; klik op ‘Add’ om de groep toe te voegen;

Figuur 4-f Groepen zoeken om hiervoor permissies aan te passen 9.

Klik ‘Write Permission’ aan bij de zojuist toegevoegde groep en klik op ‘Save’. Hiermee keert u terug naar het eerste scherm. Bij de zojuist toegevoegde groep ziet u dat ‘write permission’ is toegekend.

4.2

Implementatie toevoegen Technische aspecten legt u vast bij een Implementatie van de Business Service. Een Implementatie is een webservice op basis van WUS of ebMS, gerealiseerd conform Digikoppeling Koppelvlakstandaarden. In het Digikoppeling Service Register gebruiken we servicetype 'SOAP Service' om een Digikoppeling WUS-service in te voeren.

U kunt een webservice (implementatie) op verschillende manieren aan het register toevoegen: 1.

SOAP Service ( Digikoppeling WUS) toevoegen door: a. Nieuwe WSDL-import; b. Bestaande webservice selecteren; c.

2.

Nieuwe handmatige invoer.

Digikoppeling ebMS Service toevoegen door: d. Nieuwe handmatige invoer; e. Bestaande webservice selecteren.

Een SOAP Service invoeren door het bijbehorende WSDL-bestand te importeren de meest eenvoudige en gebruiksvriendelijke manier. Handmatige invoer van een nieuwe SOAP Service wordt hier niet beschreven. Een ebMS Service moet u vooralsnog handmatig invoeren. Vooraf: Implementatietype selecteren Pagina 16 van 39


Een Implementatie (webservice) voegt u toe aan een Business Service. Kies daarom eerst de juiste Business Service in het register (zie hoofdstuk 2). Vervolgens geeft u aan welk type Implementatie u wilt toevoegen: WUS (SOAP Service) of ebMS (Digikoppeling ebMS Service).

Figuur 4-g Keuze van toe te voegen Implementatie Klik hiervoor op het scherm met gegevens van de Business Service, onderaan de sectie ‘Implementations’, op ‘Add SOAP Service’ respectievelijk ‘Add Digikoppeling ebMS Service’. Over de vervolgstappen leest u hierna meer. Opmerking: indien de 'Implementations'-sectie niet wordt getoond, dient u de ‘view’ van het scherm aan te passen (onder ‘Views’ bovenaan het scherm). 4.2.1

SOAP Service (Digikoppeling WUS) Voeg een SOAP Service toe door het WSDL-bestand te importeren dat de webservice beschrijft. Hierdoor worden alle relevante gegevens automatisch vertaald naar de juiste elementen in het Digikoppeling Service Register. Een aantal attributen — meta-informatie, die niet is opgenomen in een WSDL — moet echter nog handmatig worden aangevuld. Hierover leest u verderop meer.

Het WSDL-bestand van SOAP Services die zijn gerealiseerd conform Digikoppeling WUS Koppelvlakstandaard bestaat uit drie bestanden, een implementation definition, een abstract definition en een message definition. Zo’n samengestelde WSDL importeert u het beste door alle bestanden op te nemen in een .zip-bestand. Voeg dit bestand ook als document toe aan de SOAP Service (zie hoofdstuk 6.3), zodat een service requester het kan downloaden.

Klik onder ‘Add SOAP Service’ op ‘From local file’. Klik vervolgens op ‘Browse…’ of ‘Bladeren…’ om het bestand van uw PC of netwerk te halen. Klik op ‘Upload’. Wilt u een samengesteld (zip-)bestand toevoegen, geef dan aan wat de ‘root-WSDL’ is (dit is normaliter de implementation definition (binding-gedeelte) van de WSDL):

Figuur 4-h Root-WSDL-bestand kiezen Klik op ‘Next’. Vervolgens verschijnt een scherm met de gegevens die zullen worden gepubliceerd: Pagina 17 van 39


Figuur 4-i Bevestiging van de ingevulde gegevens De naam van de SOAP Service is automatisch afgeleid van het ‘servicename’-attribuut in de WSDL. Naam en beschrijving kunt u eventueel aanpassen. Het is zeer aan te raden om in de naam en beschrijving op te nemen welk Digikoppeling profiel gebruikt is voor de service. Door aan te geven welke profiel gebruikt is, kan een afnemende partij via het koppelvlakstandaard document de relevante detail informatie ophalen. Als naamgevingsconventie dient het volgende aangehouden te worden: _<SERVICE-NAAM>_ Klik op ‘Finish’. U ziet nu het ‘Service details’-scherm.

Figuur 4-j Het scherm ‘Service details’ De relevante elementen worden automatisch gegenereerd. Normaal gesproken zijn dit:  Het geïmporteerde WSDL-bestand.  Bijgevoegde bestanden, zoals XSD’s.  Eén of meer endpoints.  Een SOAP Service. Klik op een element om het te bekijken. Klik op ‘OK’ om het scherm af te sluiten. De WUS-service is opgeslagen in het Serviceregister als SOAP Service (Implementation) en Endpoint(s). Reliable messaging voor WUS Indien het gaat om een melding service in WUS is het mogelijk om de afnemende partijen te ondersteunen door WS-policies op te nemen in de WSDL. Binnen Digikoppeling is het gebruik van WS-Policies optioneel omdat niet alle technische partijen het gebruik van de policies eenduidig ondersteunen. Niettemin is het faciliteren van het gebruik van WS-Policies Pagina 18 van 39


aan te raden omdat dit het implementatie proces in verre mate kan versimpelen. Indien gebruik wordt gemaakt van de WS-Policies is het aan te raden om een tweede ‘Soap service’ implementatie toe te voegen waarbij deze WSDL gebruik maakt van WS-Policies referenties. De betreffende policies worden via een WSDL import toegevoegd. Door de policies apart te importeren, is het mogelijk om framework specifieke policy sets op te stellen en deze eenvoudig in de bestaande sets te vervangen danwel aanvullen. Alle WSDL imports (dus inclusief de policies) dienen als documenten onder de SOAP services zijn opgenomen. Indien er framework specifieke policy bestanden zijn opgenomen dient de naam van de framework meegenomen te zijn in de naam van policy bestand. Gegevens aanvullen Vervolgens vult u handmatig enkele servicegegevens aan. Klik hiervoor op de naam van de SOAP Service en in het ‘SOAP Service’-scherm op ‘Edit’. Vul bij de volgende velden de relevante gegevens in: Attribuut

Digikoppeling WUS

Waarde

Opmerkingen

‘true’

Service Voldoet aan Digikoppeling ‘true’

Alleen als Digikoppeling -

WUS-specificatie

compliant. Voeg in dit geval ten minste een Digikoppeling Compliance Document toe waarmee u aantoont dat de service is getest met Digikoppeling Compliancevoorziening WUS.

Relevante documenten

Zie hierboven

toegevoegd Service lifecycle

Selecteer een waarde

Failure impact

Selecteer een waarde Optioneel

Versienr.

Nummer

Klik op ‘Save’ om de wijzigingen op te slaan. Permissies van de Implementatie aanpassen Degene die een Implementatie invoert is automatisch ‘eigenaar’ van de betreffende gegevens. Dit betekent dat alleen die persoon de gegevens mag wijzigen; deze persoon beschikt immers over de juiste ‘permissies’. Voor het register is echter afgesproken dat alle gebruikers binnen een organisatie die als service provider kunnen inloggen, deze gegevens moeten kunnen wijzigen. Hiervoor moet u de permissies voor de Implementatie aanpassen. Dit werkt hetzelfde als voor Business Services; zie hierboven.

Pagina 19 van 39


4.2.2

Digikoppeling ebMS Service Een webservice-implementatie volgens Digikoppeling ebMS Koppelvlakstandaard voegt u handmatig toe. Het is belangrijk dat u ook de benodigde servicedocumentatie opneemt:  ebMS Service Secificatie (ESS)  CPA-template (als aanwezig)  XSD-bestand(en) met berichtdefinities We nemen aan dat u bij het creëren van specificaties voor een ebMS Service de CPA-Creatievoorziening van Digikoppeling gebruikt om een CPA (Collaboration Protocol Agreement, het contract tussen service provider en service requester) te genereren. Om deze voorziening te gebruiken dient een 'ebMS Service Specification'-document aan de servicedefinitie te worden toegevoegd. Wilt u geen gebruikmaken van de CPACreatievoorziening, dan kunt u een 'CPATemplate' gebruiken. Kies de juiste Business Service. Klik onder ‘Add Digikoppeling ebMS Service’ op ‘New Digikoppeling ebMS Service’. Het volgende scherm verschijnt:

Figuur 4-k Een ebMS Service publiceren Vul de verschillende velden in en klik op ‘Save’ om de ebMS Service in het Serviceregister op te slaan. Servicespecificaties toevoegen Voeg vervolgens de benodigde specificaties (documenten) toe. Voeg technische contractbestanden (ESS en/of CPA Template, XSD, enzovoort) toe aan de Implementatie als .zip-bestand. Dit vereenvoudigt het downloaden van deze Pagina 20 van 39


bestanden door een service requester.

Figuur 4-l Documenten toevoegen door een ‘relationship’ te creëren Vul de verschillende velden in en klik op ‘Save’ om de ebMS Service in het Serviceregister op te slaan. Gebruik voor de naam van de ebMS Service bij voorkeur de naam zoals die ook in de ESS voor de service is opgenomen. In de ESS is deze naam te vinden bij het 'messages'element: <messages process="procesNaam" service="VoorbeeldService:1:0"> De servicenaam wordt ook door de CPA-Creatievoorziening gebruikt om de service te identificeren. Met andere woorden, een consumer zal deze naam nodig hebben om met behulp van de CPA-CV een CPA voor deze service te maken. Opmerking: in de ESS wordt de servicenaam gebruikelijk weergegeven volgens de URNsyntax. Onderdelen van de naam worden daarbij gescheiden door een dubbele punt. In Serviceregister en CPA-Creatievoorziening dienen eventuele dubbele punten te worden vervangen door 'gewone' punten. Voorbeeld: “VoorbeeldService:1:0” wordt “VoorbeeldService.1.0” Attribuut Naam Omschrijving

Waarde

Versienummer

0.1, 1.0, 1.5, etc.

Versienummer Koppelvlak- 1.0 etc. standaard Voldoet aan DIGIKOPPELING ebMSspecificatie

Opmerkingen Zie opmerkingen in de box hierboven. Een korte, heldere omschrijving die helpt de service te identificeren, bijvoorbeeld in een lijst van services. Zorg ervoor dat deze waarde overeenkomt met het versienummer in de servicenaam, indien ook hierin opgenomen. Het versienummer van de ebMS Koppelvlakstandaard volgens welke de service is gerealiseerd. Alleen als de service feitelijk Digikoppeling -compliant is. Voeg in dit geval ten minste een Digikoppeling Compliance Document toe waarmee u aantoont dat de service is getest met Pagina 21 van 39


Relevante documenten toegevoegd

Digikoppeling Compliancevoorziening ebMS. Zie hierboven.

Servicespecificaties toevoegen Voeg vervolgens de benodigde specificaties (documenten) toe. Voeg technische contractbestanden (ESS en/of CPA Template, XSD, enzovoort) toe aan de Implementatie als .zip-bestand. Dit vereenvoudigt het downloaden van deze bestanden door een service requester. Voeg het .zip-bestand toe via de Documents-sectie van het 'ebMS Service'-scherm (zie 4.3.Documentatie toevoegen voor een gedetailleerde beschrijving).

Figuur 4-m Bevestiging 4.3

Documentatie toevoegen Naast technische contractbeschrijvingen kunt u aanvullende documentatie toevoegen, aan zowel een Business Service als een Implementatie. Denk aan procesbeschrijvingen en (functioneel) ontwerpen, maar ook aan beschrijvingen van voorwaarden voor het gebruik van een service. Documentatie toevoegen gebeurt voor alle artefacten (Business Service, SOAP Service enzovoort) op dezelfde manier. In deze paragraaf wordt het toevoegen van aanvullende documentatie beschreven voor een WUS Service (SOAP Service). De schermen en functies hieronder kunt u ook openen vanuit de tab ‘Tools’. In dat geval zien ze er anders uit; ze staan in een andere 'view'. Wijzig de view in 'Services'. Voeg technische contractbestanden (ESS, WSDL, XSD) toe aan de Implementatie als .zip-bestand. Dit vereenvoudigt het downloaden van deze bestanden door een service requester. Klik op de tab ‘Services’ onder ‘View’, links in het scherm, op ‘My Services’. Klik vervolgens op de Business Service waaraan u de SOAP Service heeft toegevoegd om die te openen. Klik op de Implementatie (SOAP Service). U ziet nu de details van de SOAP Service.

Pagina 22 van 39


Figuur 4-n Een bestand toevoegen aan een Implementatie Kies onder ‘Add Document’ of u een bestand wilt kiezen op uw PC of netwerk. U kunt ook een link naar het bestand opnemen; het bestand zelf wordt dan niet in het Register opgeslagen. Kies vervolgens het juiste bestand en vul bestandsnaam, -omschrijving en -type in (bijvoorbeeld ‘Digikoppeling Compliance Document’). Hanteer hierbij de hieronder beschreven naamgevingsconventie.

Naamgeving van documenten Documenten die aan artefacten worden toegevoegd worden alle opgeslagen in de 'Catalog' van het DIGIKOPPELING Service Register. Om documenten ook in deze Catalog identificeerbaar te maken, is het goed om een naamgevingsconventie te hanteren. Voor documenten wordt een naamgeving voorgesteld analoog aan die voor services: < orgAfkorting >_< serviceID >_documentID >_< versieNr. > orgAfkorting: serviceID: documentID: versieNr.:

de in het OSR gehanteerde afkorting voor de eigen organisatie; een korte 'identifier' voor de service (1 of 2 steekwoorden); een korte 'identifier' voor het document; indien van toepassing, het versienummer van het document.

Voorbeelden: ICTU_TMF_Aanmelden_UC001_MeldGeredeTwijfel ('use case'-beschrijving voor een TMF-service, opgenomen bij Business Service) ICTU_TMF_Aanmelden_DIGIKOPPELING-S794nxsnl-server-certificaat (document dat de publieke sleutel van een certificaat behorend bij een service op een specifieke omgeving bevat, opgenomen bij de service Implementatie).

Pagina 23 van 39


Het Serviceregister kent een aantal voorgedefineerde documenttypen: Type document:

Bedoeld voor:

Toevoegen aan artefact:

ebMS Consumer Specification

Een service requester's ebMS Consumer Specification.

ebMS Service Specification

Een service provider's ebMS Service Specification.

ebMS Service Implemetatie

CPA Template

CPA Template

ebMS Service Implemetatie (optioneel)

ebXML CP(P)A

CPA-document

Consumption Request

PKI Certificate

Publieke deel van client en/of servercertificaten (zie verder onder 4.4)

Service implementatie (WUS of ebMS)

DIGIKOPPELING Compliance Document

Documenten die aantonen dat de service DIGIKOPPELING-compliant is (is gerealiseerd conform Digikoppeling Koppelvlakstandaarden)

Business Service

Detailed Design

Detailontwerp

Business Service of Service Implementatie

Functional Specification

Functionele beschrijving van de service, o.a. 'use case'-beschrijvingen.

Business Service

Technical Specification

Technisch ontwerp

Service Implementatie

Installation Instructions

Installatiehandleidingen

Service Implementatie

User Manual

Gebruikershandleidingen

Business Service of Service Implementatie

Kies het juiste documenttype voor uw document. Klik op 'Save' om het bestand aan de Service toe te voegen. 4.4

Certificaten toevoegen Een belangrijk aspect voor de beveiliging van Digikoppeling is de juiste identificatie, authenticatie en autorisatie van (overheids-)organisaties. Digikoppeling maakt hiervoor gebruik van een PKI-infrastructuur met certificaten. Voor Digikoppeling is daarbij gekozen voor certificaten die voldoen aan de eisen van PKIoverheid. Identificatie en authenticatie van organisaties vindt plaats middels het OverheidsIdentificatieNummer (OIN), een organisatie-identicerend nummer dat is opgenomen in het certificaat. Het OIN dient derhalve aan organisaties ter beschikking te worden gesteld. Aangezien Digikoppeling gebruik maakt van tweezijdige beveiliging (tweezijdig SSL) dienen beide bij berichtuitwisseling betrokken partijen te beschikken over elkaars OIN. Om ervoor te zorgen dat organisaties onder alle omstandigheden over elkaars publieke sleutels kunnen beschikken, is afgesproken dat een organisatie in alle gevallen zijn publieke sleutel(s) in het Serviceregister publiceert. Partijen hebben op deze manier ook toegang tot elkanders OIN. Let op: indien het gaat om een SOAP service dat gebruik maakt van Encryptie, dient het publieke certificaat dat gebruikt moet worden voor de encryptie toegevoegd te worden. Zonder het meeleveren van een publiek Pagina 24 van 39


certificaat is het namelijk niet mogelijk voor de verzendende partij, om het bericht te versleutelen. Let op: het Serviceregister is er niet voor bedoeld om sleutels/certificaten te valideren. Het speelt puur een rol bij het distribueren van deze gegevens. http://localhost:10080/demows.wsdl Hoe kunnen certificaten in het OSR worden opgenomen? Certificaten worden in het Serviceregister opgenomen als document van het type 'PKI certificate'. http://localhost:10080/demows.wsdl Waar worden certificaten opgenomen? Certificaten worden als document type “PKI Certificate” opgenomen bij de service implementatie(s) (WUS of ebMS) waarvoor ze relevant zijn.

Pagina 25 van 39


5

Services zoeken

Organisaties kunnen op vier manieren zoeken naar services: 1.

Zoeken op Business Service

2.

Zoeken op vrije tekst

3.

Zoeken op webservice (Implementatie)

4.

Zoeken op aanbieder (Organisatie)

Zoeken op Business Service heeft de voorkeur, omdat u hiermee direct een overzicht krijgt van beschikbare services. Zoeken op vrije tekst geeft als resultaat een overzicht van alle passende artefacten in de catalogus. Zoeken op webservice of op aanbieder is alleen praktisch als u al kennis heeft over de af te nemen service of van de aanbieder ervan. Met ‘artefact’ bedoelen we de hoofdcategorieën waarin gegevens in het register zijn ingedeeld. Bijvoorbeeld ‘Business Service’, ‘SOAP Service’, ‘ebMS Service’, ‘Organization’ en ‘Contact’. We leggen alle vier de zoek methoden hierna uit. 5.1

Zoeken op Business Service Klik op de tab ‘Services’ om te zoeken op Business Services. Het volgende scherm verschijnt:

Figuur 5-a De tab 'Services' in het menu In het menu ‘View’, links in het scherm, vindt u verschillende weergaven ('views') voor gepubliceerde services: Consumable Services Een overzicht van alle services die ‘in productie’ zijn en die u dus kunt afnemen. All Services Een overzicht van alle services in het Register. Het kan zijn dat u in deze lijst alleen services ziet waarvoor u geautoriseerd bent. My Services Een overzicht van alle services die u zelf in het register hebt ingevoerd. Pagina 26 van 39


Klik op een van de knoppen om het bijbehorende overzicht te bekijken.

Figuur 5-b Service zoeken via ‘All Services’ Klik op de naam van de service om details van de service te bekijken. Als u hiervoor bent geautoriseerd (rol = provider) kunt u de service ook bewerken. 5.1.1

Resultaat sorteren Sorteer de resultaten door op de labels boven de kolom te klikken.

Figuur 5-c Resultaten sorteren Klik bijvoorbeeld op ‘Name’ om de services alfabetisch (aflopend) te sorteren op naam. Bij deze sortering wordt deze volgorde gehanteerd:  Naam begint met een cijfer (0-9).  Naam begint met een vreemd karakter (@, #, $ enzovoort).  Naam begint met een hoofdletter (a-z).  Naam begint met een kleine letter (a-z). Klik nogmaals op ‘Name’ om de volgorde om te draaien (oplopend). 5.1.2

Resultaat verfijnen met zoekfilter Het Serviceregister zal naar verwachting grote aantallen services gaan genereren. Het zal dan ook vaak nodig zijn om het zoekresultaat te verfijnen. Dit is mogelijk via de ‘Find’-functie.

Pagina 27 van 39


Figuur 5-d Locatie van de ‘Find’-functie Klik op ‘Find’. De ‘Find’-functie wordt getoond:

Figuur 5-e Opties onder de ‘Find’-functie Met de ‘Find’-functie past u een zoekfilter toe. Hiermee verfijnt u het zoekresultaat. Vul een filterwaarde in, in het veld ‘Find’. Hierbij geldt:  Geen ‘wildcards’; de functie voegt automatisch wildcards toe voor en na het filter. ‘Er’ wordt bijvoorbeeld geïnterpreteerd als ‘*er*’.  Het veld is niet hoofdlettergevoelig (‘bb’, ‘bB’ en ‘BB’ leveren hetzelfde resultaat op). In het keuzevak ‘in’ kiest u één van de servicekenmerken (attributen genaamd) waarop u kunt filteren. Vul de waarde in waarop u wilt filteren, kies een kenmerk en klik op ‘find’. Het zoekresultaat wordt gefilterd: alleen de services die passen bij uw filter worden getoond. Desgewenst kunt u op dezelfde manier nóg een filter toepassen. Klik op ‘Clear’ om de filtering ongedaan te maken. 5.1.3

Aantal getoonde services aanpassen U kunt het aantal getoonde services aanpassen. Standaard ziet u 10 services; u kunt dit uitbreiden naar 20 of 50.

Figuur 5-f Aanpassen aantal getoonde services Klik op het gewenste aantal om het aantal getoonde services aan te passen. 5.1.4

Door het overzicht navigeren Het kan zijn dat niet alle services op één pagina passen, zelfs als u een filter heeft toegepast of het aantal getoonde services heeft gewijzigd. U

Pagina 28 van 39


kunt dan ook door de verschillende pagina’s van het zoekresultaat navigeren.

Figuur 5-g Navigeren door het zoekresultaat In bovenstaand voorbeeld is het zoekresultaat verdeeld over drie pagina’s. Klik op de cijfers om de andere pagina’s te bekijken. Klik op ‘Next’ of ‘Last’ om naar de volgende, dan wel de laatste pagina te gaan; klik op ‘Previous’ of ‘First’ om naar de vorige respectievelijk de eerste pagina te gaan. 5.2

Zoeken op vrije tekst Zoek op vrije tekst door in het menu ‘Search’, linksboven in het scherm, een trefwoord in te voeren en op ‘Go’ te klikken.

Figuur 5-h Zoeken op vrije tekst Vervolgens ziet u een lijst met alle artefacten in de catalogus waarin uw trefwoord voorkomt, in:  Naam  Omschrijving  Eventueel meegegeven zoektermen

Figuur 5-i Resultaatscherm na zoeken op vrije tekst U kunt het zoekresultaat nader specificeren, door in het keuzevak ‘Scope’ een keuze te maken en op ‘Search’ te klikken. Kies bijvoorbeeld ‘Business Service’ om het resultaat te beperken tot Business Services. Klik op de naam van een service om over de betreffende service meer informatie te bekijken.

Pagina 29 van 39


Extra opties bij zoeken Bij het invoeren van trefwoorden in het zoekveld kunt u:  Meerdere trefwoorden invullen, gescheiden door spaties of komma’s. Het Register zoekt dan op de ene óf de andere term.  Wildcards (*) gebruiken om op een deel van een trefwoord te zoeken. Zoeken op vrije tekst maakt geen onderscheid tussen hoofd- en kleine letters. 5.3

Zoeken op Implementatie Implementaties van webservices, die aan een Business Service zijn toegevoegd, worden onder de betreffende Business Service weergegeven. U kunt webservice-Implementaties ook afzonderlijk vinden. Klik hiervoor op de tab ‘Tools’. Het volgende scherm verschijnt:

Figuur 5-j De tab ‘tools’ met ‘Implementations’ uitgelicht Klik onder ‘SOA’ (service-oriented architecture) op ‘Implementations’. De vier Implementatietypen in het Serviceregister verschijnen. Voor de eerste versie van het Register zijn alleen de typen ‘SOAP Services’ en ‘Digikoppeling ebMS Services’ van belang. Klik op een van beide typen om de services van het betreffende type te bekijken. Het zoekresultaat kunt u vervolgens verder verfijnen. Opmerking: bekijk dit scherm in de 'Services view', anders worden de knoppen ‘Accept’ en ‘Reject’ niet getoond. Zoeken op aanbieder Als u de aanbieder van een bepaalde service kent, kunt u direct een overzicht services bekijken die de betreffende organisatie aanbiedt. Klik hiervoor op de tab ‘Tools’.

Pagina 30 van 39


Figuur 5-k De tab ‘tools’ met ‘Organisaties’ uitgelicht Klik onder ‘Content’ op ‘Contacts’ en vervolgens op ‘Organisaties’. Een overzicht van alle organisaties verschijnt. Het zoekresultaat kunt u vervolgens verder verfijnen. Klik op de naam van een organisatie om de services van deze organisatie te bekijken.

Pagina 31 van 39


6

Bericht 'broadcasting': generieke servicedefinities

Soms wil een overheidsorganisatie berichten naar een groot aantal andere organisaties verzenden ('broadcasting'). Dit betekent dat alle ontvangende organisaties over een service moeten beschikken die dit bericht kan ontvangen. In het geval van een implementatie op basis van WUS zullen de hierbij gehanteerde WSDL's voor alle ontvangers nagenoeg gelijk zijn; feitelijk is hierin alleen het ‘endpoint’ anders. Het ligt dan ook voor de hand om een 'generieke servicedefinitie' (lees: WSDL-template) aan te bieden. Een partij die de service feitelijk implementeert (berichten wil ontvangen), zal dat doen op basis van deze WSDL-template: alleen het juiste endpoint hoeft hierin ingevuld te worden. In het geval van een implementatie op basis van ebMS ligt dit een slag anders: aan de berichtuitwisseling ligt in dit geval een CPA ten grondslag, waarin onder meer de 'endpoints' van beide partijen zijn opgenomen. Vanaf ebMS Koppelvlakstandaard versie 1.1 is het bovendien mogelijk om in een CPA een volledige 'berichtenroundtrip' (procesbeschrijving) op te nemen (bijvoorbeeld: A zendt bericht aan B, B retourneert antwoordbericht aan A, etc.; hierbij kunnen zelfs meerde partijen zijn betrokken). In de ebMS Service Specificatie (ESS), die door de service provider wordt aangeleverd, wordt het endpoint van de 'broadcasting' partij opgenomen. De CPA komt vervolgens tot stand op de wijze waarop dit altijd gebeurt: de 'consumerende' partij creëert een ebMS Consumper Specification (ECS) waaruit, in combinatie met de ESS, de CPA wordt gegenereerd. Het implementeren van een 'broadcast'-situatie vraagt in het geval van WUS dus een generieke servicedefinitie, waarvan gegevens in het Digikoppeling Service Register zullen worden gepubliceerd. Hieronder wordt beschreven hoe een en ander in zijn werk gaat. WUS: ‘generieke’ servicedefinitie Zoals hierboven aangegeven stelt de verzendende organisatie een ‘generieke servicedefinitie’ of ‘generieke contractbeschrijving’ (of WSDLtemplate) beschikbaar om een 'broadcasting' vorm van berichtuitwisseling mogelijk te maken. Deze generieke definitie is incompleet, want in elk geval ontbreekt het endpoint. Ontvangende organisaties kunnen de generieke contractbeschrijving voltooien door het juiste endpoint op te nemen, om zo een volwaardig servicecontract (WSDL) te creëren. ‘Bericht-provider’ versus ‘service provider’ Een organisatie die een service publiceert op basis van een generieke servicedefinitie, ontvangt daarmee niet automatisch ook de berichten van de organisatie die voor de generieke definitie verantwoordelijk is. Overleg is nodig om een feitelijke (servicegerichte) verbinding te realiseren. Daarom is het voor de leverancier van de generieke definitie belangrijk om een overzicht te hebben van alle implementaties, die op basis van zijn definitie zijn gemaakt (merk op dat deze relatie in het geval van ebMS reeds via de CPA('s) is gelegd).

Pagina 32 van 39


Mogelijk is het verwarrend dat de implementerende partij (technisch gezien) acteert als service provider en de partij die de generieke definitie heeft opgesteld (en die uiteindelijk de berichten naar de service gaat sturen!) als service requester. Dit lijkt een omgekeerde weg: de partij in de rol van service provider dient nu aan de partij die de berichten verstuurt te melden dat er een service is gemaakt op basis van de aangeboden generieke definitie, zodat ook deze nieuwe service de berichten kan ontvangen. In de praktijk zullen er altijd (ook) afspraken op papier zijn gemaakt tussen de betrokken partijen. Het feitelijk implementeren van de service die nodig is om de berichten te kunnen ontvangen is hiermee in feite het sluitstuk op de overeenkomst. Generieke servicedefinities in het register herkennen Waaraan herkent u een generieke servicedefinitie in het DIGIKOPPELING Service Register: Er is uitsluitend een Business Service. Omdat er geen feitelijke implementatie is, worden geen Implementaties aan de Business Service toegevoegd; De naam en beschrijving van de Business Service geven aan dat het om een generieke servicedefinitie gaat. De bestanden waarmee het ‘generieke contract’ wordt beschreven — servicedefinitie zonder endpoint; berichtdefinities — zijn als .zip-bestand aan de Business Service toegevoegd, en niet, zoals gebruikelijk, aan de Implementatie. Als er meerdere Implementaties (webservices) zijn gedefinieerd onder de Business Service, dan bevat de Business Service een apart .zip-bestand per Implementatie. 6.1

Generieke service aanmaken Om een generieke service aan te maken, maakt u eerst een nieuwe Business Service. Een beschrijving hiervan leest u in hoofdstuk 3.1. Voor een generieke service hanteert u de naamgevingsconventies, gevolgd door het achtervoegsel (suffix) ‘genDef’. Voorbeeld: < orgAfkorting >_< functie/taak >_< versieNr >_ genDef Eventueel neemt u meer ‘identificerende’ onderdelen in de naam op: < orgAfkorting >_< object >_< functie/taak >_< “wet-kenmerk”>_< “groep-ID” >_< versieNr>_ genDef Partijen die een service creëren, op basis van deze generieke definitie, laten het achtervoegsel ‘genDef’ weg en vervangen slechts de < orgAfkorting > door de afkorting van hun eigen organisatie. De rest van de servicenaam blijft ongewijzigd. Zo zijn met één zoekopdracht alle services, op basis van een generieke definitie, in het register terug te

vinden. Houd u verder aan voorwaarden en formaat voor de verschillende velden:

Pagina 33 van 39


Veld Naam

Omschrijving

Lifecycle Stage

Versienummer Enable Consumption Zoektermen

Associated Approval Provider

Service wordt verwijderd op

Voorwaarde(n), formaat, opmerkingen Verplicht; zie naamgevingsconventies. Essentieel is het achtervoegsel ‘genDef’, bijvoorbeeld: ICTU_OntvangService_v0.1_genDef. De eerste 30 karakters van de omschrijving zijn zichtbaar in het overzichtsscherm waarin beschikbare services worden getoond. Op basis van deze omschrijving is de service mede te identificeren. Gebruik daarom een korte, eenduidige omschrijving. Bijvoorbeeld: GenDef ICTU OntvangService_v0.1 Generieke definitie tbv de OntvangService. Het gaat in dit geval om de lifecycle stage van de generieke servicedefinitie. Een generieke service zal het meest worden aangeboden als de definitie ‘in productie’ (of mogelijk ‘in preproductie’) is. Numerieke versieaanduiding, bijvoorbeeld 0.1, 0.2, 1.0, 2.0 enzovoort. Niet van toepassing voor een generieke service; dit veld mag niet aangevinkt zijn. Kommagescheiden lijst van zoektermen. Op basis van deze termen kan de gebruiker snel een service vinden ,via 'zoeken op vrije tekst'. Neem hierin op: De naam van de organisatie die de service aanbiedt. Overige delen van de naam van de service (uitgeschreven, niet afgekort). Basisregistratie, gegevensbron, of bijvoorbeeld wetgeving waar de service betrekking op heeft. Onderscheid: is het een generieke service? (neem zoektermen als 'generiek' en 'generic' op). Vooralsnog niet gebruikt. Kies uw eigen organisatie uit de lijst. De lijst verschijnt als u op ‘Provider’ klikt. U ziet in de lijst ook gebruikersgegevens, maar kies alleen uw eigen organisatie. Datum; alleen invullen als de service op de nominatie staat verwijderd te worden.

Vervolgens past u de permissies van de Business Service aan en voegt u de generieke contractdefinitie toe (WSDL, XDS; geen feitelijke endpoints). Documenten die bij één implementatie horen, voegt u toe in een .zipbestand. Meer hierover leest u in hoofdstuk 3.3. 6.2

Implementeren op basis van generieke service Wil uw organisatie een service implementeren, op basis van een generieke servicedefinitie? Dan biedt u deze service aan in de rol van ‘service provider’. Daarom maakt u een nieuwe Business Service aan, waarvoor de generieke definitie als uitgangspunt dient. Het is vooral belangrijk om de juiste naamgevingsconventies te hanteren (zie hiervoor paragraaf 5.1). Hierdoor zijn van de generieke servicedefinitie afgeleide services eenvoudig terug te vinden. Zoek eerst de gewenste generieke service in het register (zie hoofdstuk 4) en download het .zip-bestand met de contractdocumenten. Maak het WSDL-bestand compleet: voeg in ieder geval het juiste endpoint toe. Maak vervolgens een .zip-bestand met daarin de gecompleteerde servicedefinitie (WSDL) en de bijbehorende berichtdefinitie(s) (XSD’s). Pagina 34 van 39


Creëer een nieuwe Business Service (zie hoofdstuk 3.1), met uw eigen organisatie als service provider. Zorg ervoor dat de naam van de service voldoet aan de naamgevingsconventies. (Als de naam van de generieke service bijvoorbeeld ‘ICTU_OntvangService_v0.1_genDef’ is, en uw organisatie is ‘ABC’, dan gebruikt u de volgende naam: ‘ABC_OntvangService_v0.1’.) Geef vervolgens in de beschrijving aan dat de service een implementatie is op basis van een generieke servicedefinitie, en vul de verschillende velden in zoals in hoofdstuk 3.1 beschreven. Voeg dan een implementatie toe aan de Business Service (zie hoofdstuk 3.2). Voeg aan de implementatie het gecompleteerde WSDL-bestand inclusief de overige contractdocumenten als .zip-bestand toe. 6.3

Procedurele aspecten Organisaties die services implementeren op basis van generieke definities, zullen op een bepaald moment de leverancier van deze generieke definitie op de hoogte moeten brengen van hun implementatie. De manier waarop we met Consumption Requests en Contracten omgaan (zie 7.Gebruiksovereenkomsten), is iets anders dan normaal. De organisatie die normaal gesproken als service requester acteert, neemt immers het initiatief. In het geval van ‘generieke services’ neemt de service requester dit initiatief pas nadat hij is geïnformeerd door de organisatie die de service heeft gerealiseerd.

Pagina 35 van 39


7

Gebruiksovereenkomsten

Om de relatie tussen service provider en service requester vast te leggen, gebruikt het Serviceregister ‘gebruiksovereenkomsten' ('Consumption Requests'). Via zulke overeenkomsten is bijvoorbeeld terug te vinden welke organisatie een bepaalde service afneemt. Om een gebruiksovereenkomst te maken, worden de volgende stappen doorlopen: 1.

U zoekt de bedoelde service in het Register.

2.

U maakt een Consumption Request (afname-overeenkomst) voor de service provider; die ontvangt automatisch bericht van het verzoek.

3.

De service provider accepteert (of verwerpt) het verzoek.

4.

De consumption request wordt in het Register automatisch omgezet in een Contract.

Lees hieronder hoe u de verschillende stappen uitvoert. 7.1

Service zoeken

Lees in hoofdstuk 2 hoe u een service zoekt. 7.2

Consumption Request maken U heeft de beoogde Business Service gevonden.

Figuur 7-a Gegevens van een Business Service met keuzemenu 'Requests' Klik boven in het scherm op ‘Requests’ en vervolgens op ‘Submit Consumption Request’. Het volgende scherm verschijnt:

Pagina 36 van 39


Figuur 7-b Selectie 'Consumer' tbv een nieuw Consumption Request Kies onder 'Select consumer' uw eigen organisatie en klik op 'Next'. Optioneel: selecteer een aan de service verbonden SLO en klik 'Next'; Pas desgewenst 'name' en vooral 'description' aan (om de Consumption Request makkelijk identificeerbaar te maken) en klik 'Next; In het geval van een Consumption Request dient ook de CPA te worden meegegeven, als onderdeel van de Request. Het CPA-document kan als document aan de Request worden toegevoegd. Het laatste scherm toont een overzicht van alle 'Consumption Request'gegevens. Controleer deze gegevens en klik op 'Next' om het verzoek naar de service provider te sturen. Indien aanpassingen gewenst zijn, klik op 'Back' om terug te keren naar het vorige scherm.

7.3

Consumption Request accepteren of verwerpen Service providers kunnen een overzicht krijgen van Consumption Requests op hun services. Ga in de 'Services'-tab naar het 'View'-menu aan de linkerkant van het scherm, en klik op 'Consumption Requests'. Dit opent het volgende scherm:

Pagina 37 van 39


Figuur 7-c Overzicht van beschikbare Consumption Requests In het scherm worden alle te beoordelen Consumption Requests getoond. Klik op een beschikbare Consumption Request. De details van de Request worden getoond als 'Contract Request' (zie volgende pagina). In het scherm wordt onder meer getoond wat de aanvragende organisatie is. Ook toegevoegde documenten zijn zichtbaar (bijv. een CPA-document in het geval van een afnameverzoek op een ebMS Service). De provider dient alle gegevens van de Request (inclusief de meegezonden documenten) te controleren, alvorens de Request te accepteren of te verwerpen. Klik op 'Accept' indien het verzoek wordt geaccepteerd. Het 'Contract Request' wordt daarmee automatisch in een 'Contract' tussen aanvrager en aanbieder omgezet. Hiermee is in het Serviceregister vastgelegd dat er een gebruiksovereenkomst bestaat tussen provider P en requester R voor service S.

Figuur 7-d Details van een 'Contract Request' Indien de Request niet kan worden geaccepteerd, klik dan op 'Reject'. De status van de Consumption Request wordt daarmee gewijzigd in Pagina 38 van 39


'rejected'. De oorspronkelijke aanvrager kan de request desgewenst corrigeren en een nieuwe aanvraag doen.

Figuur 7-e Overzicht van Consumption Requests en hun status

7.4

Servicegegevens gebruiken Indien een service provider en een service requester tot een gebruikersovereenkomst zijn gekomen, dient de service requester zijn informatiesysteem zodanig aan te passen dat berichten naar de service te verzenden zijn. WUS Service Voor de benodigde software-ontwikkeling zullen, in het geval van een WUS Service, in ieder geval de 'contractdocumenten' van de service benodigd zijn (WSDL, XSD). Deze zijn te downloaden onder de WUSImplementatie van de betreffende Business Service (ervan uitgaande dat de documenten als .zip-bestand aan de Implementatie zijn toegevoegd). Klik op het .zip-bestand om de documenten te downloaden. ebMS Service Voor de benodigde software-ontwikkeling zullen, in het geval van een ebMS Service, de berichtdefinities (XSD) en de CPA benodigd zijn. De berichtdefinities zijn te downloaden onder de ebMS-Implementatie van de betreffende Business Service (ervan uitgaande dat de documenten als .zip-bestand aan de Implementatie zijn toegevoegd). De CPA is onderdeel van het Contract dat in het Serviceregister is opgenomen, als gevolg van het accepteren van de Consumption Request die aanvrager aan aanbieder heeft gedaan.

Pagina 39 van 39

Gebruikershandleiding Digikoppeling Serviceregister

Recommend Documents