1      Formål

Nærværende dokument indgår i den samlede dokumentationspakke for stamdataregistret på NSP. Dokumentationspakken giver tilsammen det fulde overblik over dokumentationen. ”Guide til anvendere” er målrettet udviklere og arkitekter hos leverandører, som ønsker at anvende funktionaliteten udstillet af stamdataservicen. Guiden kan indeholde kodeeksempler, interaktionsbeskrivelser, servicebeskrivelser, snitfladebeskrivelser mv.

2      Introduktion til Stamdataservicen

Stamdataservicen er en national service udstillet på NSP, som giver adgang til relevante nationale stamdataregistre, opsamlet af NSP fra forskellige myndigheder og dataansvarlige enheder.

Stamdataservicen udstiller flere snitflader, der tilsammen giver mulighed for både at holde komplette lokale kopier af stamdataregistrene ajour og for at lave enkeltopslag i udvalgte registre. For en overordnet beskrivelse af den udstillede funktionalitet henvises der til Arkitektur og Design, der på lige fod med nærværende dokument indgår i den samlede dokumentationspakke for stamdataservicen.

2.1     Adgang til Stamdataservicens funktionalitet

Anvendelse af stamdataservicen forudsætter en aftale med NSP-operatøren. Yderligere oplysninger om betingelserne for anvendelse af stamdataservicen, herunder håndtering af dataansvar og tekniske forudsætninger, kan fås ved henvendelse til NSP-operatørens servicedesk (http://nsp.nsi.dk). Adgangen til funktionaliteten er styret i flere ”lag”, idet de enkelte stamdataregistre indeholder forskelligartet information, og kan være styret af forskellige politikker. I praksis styres adgangen gennem whitelists på CVR-nummer-niveau [1] for de enkelte services.   

Alle snitflader udstillet af stamdataservicen er baseret på Den Gode Web-Service 1.0.1 (DGWS 1.0.1) som er en national standard for identitetsbaserede webservices i sundhedssektoren. I forhold til stamdataservicen forudsættes der autentifikation på DGWS niveau 3, dvs. brug af STS-signerede system-IDkort.

NSI leverer gratis biblioteksunderstøttelse af store dele af webservice kommunikationen, herunder generering og parsning af ID-kort og headere. Der henvises til DGWS-dokumentationen (http://www.medcom.dk/wm110731) for generel information om DGWS og SEAL-dokumentationen (http://www.sosi.dk/twiki/bin/view/ProjectManagement/SOSIProducts) for generel information om biblioteksunderstøttelsen.

...

[1] Det er forventningen, at det er i nær fremtid bliver muligt at adgangsstyre på system-niveau.

...

3      Kopiregisterservicen (KRS)

Kopiregisterservicen (KRS) giver systemer mulighed for at etablere og ajourføre en lokal kopi af et register, som f.eks. CPR-registret eller autorisationsregistret.

Som beskrevet i afsnit 2.1 er det nødvendigt at etablere en aftale hos NSP-operatøren for at få adgang til de respektive registre. Præcist hvilke registre og data-typer man får adgang til er afhængigt af aftalen. Der henvises til dokumentet Design og Arkitektur for en oversigt over hvilke registre, KRS pt. kan levere data fra.

3.1     Struktur af kald til KRS

Kopiregisterservicen tager følgende input:

Kaldet til Kopiregisterservicen er formelt specificeret i WSDL’en stamdata_krs.wsdl, der kan rekvireres ved henvendelse til NSP-operatøren. En komplet gennemgang af tilgængelige registre, datatyper samt versioner er at finde i dokumentet ”Registerspecifikation for Anvendere”.

3.2     Fejlsituationer

Hvis der er en fejl i forespørgslen eller der opstår en fejl på serveren vil servicen returnere en fejlmelding af typen ReplicationFault med en beskrivelse af fejlen (jævnfør WSDL som specificeret i ovenstående afsnit). Hvis forespørgslen går godt returnerer servicen en besked af typen ReplicationResponse der indeholder et ”any”-element. Dette any-element er af typen atom baseret på ATOM 1.0 [RFC4287]. ATOM er en syndikeringsprotokol og designet til at holde styr på ændringer i en ressource. I dette tilfælde er ressourcerne datatyperne i et register. Hvordan dette atom-element skal tolkes er forklaret nærmere i afsnit 3.3.

3.3     Endpoint URL

Kopi register-servicen er som udgangspunk konfigureret på:

<hostnavn>:8080/stamdata-batch-copy-ws/service/StamdataReplication

og wsdl kan hentes ved at sætte ?wsdl efter:

<hostnavn>:8080/stamdata-batch-copy-ws/service/StamdataReplication?wsdl

1.3     Eksempel på kald til KRS

Som klient sender man et ReplicationRequest til servicen:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
         …
  </S:Header>
  <S:Body>
    <ns1:ReplicationRequest xmlns:ns1="http://nsi.dk/2011/10/21/StamdataKrs/">
      <register>cpr</register>
      <datatype>person</datatype>
      <version>1</version>
      <offset>0</offset>
    </ns1:ReplicationRequest>
  </S:Body>
</S:Envelope>

Headeren skal indeholde en DGWS 1.0.1 header.

Hvis alt går som forventet og forespørgslen bliver godkendt modtages et svar:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
         …
  </S:Header>
  <S:Body>
    <ns1:ReplicationResponse xmlns:ns1="http://nsi.dk/2011/10/21/StamdataKrs/">
      <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://nsi.dk/-/stamdata/3.0/cpr">
        <atom:id>tag:nsi.dkersonLookupWithSubscriptionIntegrationTest.java,2011:cpr/person/v1</atom:id>
        <atom:updated>2011-10-25T07:02:08.045Z</atom:updated>
        <atom:title>Stamdata Registry Feed</atom:title>
        <atom:author>
          <atom:name>National Sundheds IT</atom:name>
        </atom:author>
         …
      </atom:feed>
    </ns1:ReplicationResponse>
  </S:Body>
</S:Envelope>

Opstår der derimod en fejl, bliver en DGWS 1.0.1 Fault sendt tilbage, f.eks.:

Fejl: