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.   

...

[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?wsdl

3.4     Eksempel på kald til KRS

Som klient sender man et ReplicationRequest til servicen:

...

<soapenv:Envelope ...>
  <soapenv:Header>...</soapenv:Header>
  <soapenv:Body>
  <soapenv:Fault>
     <faultcode>Server</faultcode>
     <detail>
       <medcom:FaultCode>expired_idcard</medcom:FaultCode>
     </detail>
     <faultstring>The ID card has expired.</faultstring>
   </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

3.5    Detaljeret svar fra KRS

Her følger et mere detaljeret output fra KRS. Tolkning af dette er beskrevet i afsnittet efter.

  <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://nsi.dk/-/stamdata/3.0/cpr">
    <atom:id>tag:nsi.dk,2011:cpr/person/v1</atom:id>
    <atom:updated>2011-11-07T09:56:12.278Z</atom:updated>
    <atom:title>Stamdata Registry Feed</atom:title>
    <atom:author>
      <atom:name>National Sundheds IT</atom:name>
    </atom:author>
    <atom:entry>
      <atom:id>tag:nsi.dk,2011:cpr/person/v1/13206597710000000085</atom:id>
      <atom:title/>
      <atom:updated>2011-11-07T09:56:11.000Z</atom:updated>
      <atom:content type="application/xml">
        <person>
          <cpr>0102451234</cpr>
          <koen>M</koen>
          <fornavn>Hans</fornavn>
          <mellemnavn/>
          <efternavn>Hansen</efternavn>
          <coNavn></coNavn>
          <lokalitet/>
          <vejnavn>Ligusterv&#xE6;nget</vejnavn>
          <bygningsnummer>42</bygningsnummer>
          <husnummer>123</husnummer>
          <etage>12</etage>
          <sideDoerNummer>th.</sideDoerNummer>
          <bynavn>Enby</bynavn>
          <postnummer>1448</postnummer>
          <postdistrikt>N&#xF8;ddebo</postdistrikt>
          <status>01</status>
          <gaeldendeCPR>3105459876</gaeldendeCPR>
          <foedselsdato>1947-12-24T00:00:00+01:00</foedselsdato>
          <stilling/>
          <vejKode>740</vejKode>
          <kommuneKode>314</kommuneKode>
          <validFrom>2011-11-07T10:56:21+01:00</validFrom>
          <validTo>2012-11-07T10:56:11+01:00</validTo>
        </person>
      </atom:content>
    </atom:entry>
  </atom:feed>

3.6     Parsing af output

Det mest interessante ved et response er ’entry’-elementerne. Hvert ’entry’-element indeholder et snapshot af en record fra registret. Med snapshot menes, at det var sådan data så ud på et bestemt tidspunkt. Stamdata bruger fuld historik når man laver et udtag. Det vil sige at man f.eks. kan få information om hvordan en person record så ud for 1 år siden – med adresse, navn etc. Der er ingen garanti for hvor langt tilbage i tiden stamdata har information. Hvert entry element har et ’content’-element som indeholder alt domæne-data. I eksemplet ovenfor er det datatypen ’person’ som er indeholdt.

Det er to slags nøgler som identificerer en record: Unikke nøgler (indeks) og versionsnumre.

3.6.1      Unikke Nøgler

Hver datatype har et nøgleelement som unikt bestemmer en record. Eksempelvis identificeres en person unikt ved sit CPR-nummer i CPR-registret. Derfor vil man, når man persisterer records fra cpr/person/v1 bruge cpr-elementet som unik nøgle. Unikke nøgler for de enkelte datatyper er beskrevet i listen over registre i dokumentet "Registerspecifikation for Anvendere”.

3.6.2      Revisionsnummer

Revisionsnumre bestemmer en record unikt indenfor en given datatype. Man kan se det som en primær nøgle i en database. Et revisionsnummer er også en slags historisk ID. Det vil sige at det bestemmer en record unikt i historien, i modsætning til unikke nøgler.

...

Med andre ord, bestemmer en unik nøgle en bestemt entitet, revisionsnummeret bestemmer et snapshot af den entitet. Begge disse numre er vigtige på flere måder. Den unikke nøgle kan optræde i flere forskellige entry-elementer. Det er på grund af at en entitet ændre sig med tiden, men revisionsnumre vil altid være forskellige.

3.6.3      DateTime

DateTime’s i data vil som udgangspunkt være repræsenteret som lokal tidszone, altså fx ”2018-07-11T08:16:47+02:00”, bemærk dog at for datoer ældre end 1894 anvendes UTC, da de moderne tidszoner ikke var indført dengang. Klienter bør derfor altid være i stand til at forstå datoer tider uanset tidszoneangivelse.

3.7     Paginering

Antallet af records i et register kan være meget stort, i visse tilfælde flere millioner records. Derfor bliver man nødt til at opdele et udtræk i flere kald. Response fra det tidligere eksempel, er et eksempel på en page. Når man er klar til at hente næste page sender man et request med nyt offset i ReplicationResponse beskeden. Offset-parameteren i næste request sættes til det sidste versionsnummeret man har modtaget. Det er muligt at angive hvor mange records man højest ønsker i et svar fra servicen ved at sætte parameteren maxRecords i ReplicationRequest-forespørgelsen. Der er på serveren en øvre grænse på denne parameter der overskriver for høje værdier i en forespørgelse. Hvis parameteren ikke specificeres i kaldet indsættes denne grænse som antal records.

4      Registre

Da der løbende kommer nye registre er beskrivelserne af de enkelte registre flyttet til:

https://www.nspop.dk/display/web/SKRS+-+Stamdata+Kopi+Register+Service#SKRS-StamdataKopiRegisterService-Registeroversigt

5      Enkeltopslag i registre

Stamdataservicen tilbyder en service til såkaldte enkeltopslag i følgende registre:

...

Enkeltopslag i et af de ovennævnte registre foregår som et webservice kald til stamdataservicen på NSP med angivelse af søgekriterier. De konkrete parametre og eventuelle særlige forhold der gør sig gældende for kald til enkeltopslags-snitfladen på stamdataservicen er beskrevet i de følgende afsnit.

5.1     Forespørgsler og dataformat

Enkeltopslags-snitfladen er udstillet som en DGWS 1.0.1 identitetsbaseret webservice. Adgang til enkeltopslagsservices forudsætter en aftale med NSP-operatøren (adgang styres på CVR-nummer). Metoderne for de udstillede registre er beskrevet i separate WSDL-filer, der kan rekvireres ved henvendelse til NSP-operatøren.

Fælles for de udstillede enkeltopslagsservices er at der kræves STS-signerede system ID-kort (dvs. DGWS niveau 3).

5.2     Enkeltopslag i autorisationsregistret

Det er muligt at lave onlineopslag i stamdataservicens kopi af Sundhedsstyrelsens autorisationsregister til fremsøgning af eventuelle autorisationer for en given sundhedsfaglig person. Metoden tager personens CPR-nummer som input, og returnerer personens navn og samtlige autorisationer, der er i kraft for vedkommende [2].

...

Hvis CPR-nummeret fra forespørgselen er tilknyttet en eller flere autorisationer vil også for- og efternavn for personen blive returneret. Forespørges der på et ugyldigt CPR-nummer eller en person uden gyldige autorisationer returneres der af sikkerhedshensyn tomme navnefelter i svaret – også selv om CPR-nummeret er et korrekt CPR-nummer for en eksisterende person.

5.2.1      Eksempel: Én eller flere autorisationer

Nedenfor ses et ”solskinsscenarie”, hvor der forespørges på en sundhedsfaglig, der har en enkelt gyldig autorisation.

...

I eksemplet er Peter Andersen tilknyttet CPR 1111122222, og han har en autorisation.

5.2.2      Eksempel: Ingen gyldige autorisationer

Forespørges der på en ikke-eksisterende person eller en person, der ikke har en gyldig autorisation, svares der blot med en tom AutorizationResponseStructure.

...

Da der ikke er nogen tilknyttede autorisationer, returneres en tom AuthorizationResponseStructure uden angivelse af for- og efternavn.

5.3     CPR-registret: Det Gode CPR-opslag

Stamdataservicen udstiller mulighed for enkeltopslag i CPR-registret gennem en implementering af ’Det Gode CPR-opslag’ som specificeret af MedCom (http://www.medcom.dk/wm110491).

5.3.1      WSDL

WSDL-filer for servicen kan findes på medcoms svn her:

...

https://fisheye.nspop.dk/browse/public/components/sdm/latest/code/nsp/cpr-ws/src/main/webapp/WEB-INF/wsdl

5.3.2      Endpoints

Det gode CPR-opslag er udstillet i version 1.0.0 og version 1.0.2, som er tilgængelige på hver deres endpoints.

...

Det anbefales at køre på version 1.0.2, da ikke alle personer kan hentes i 1.0.0 uden valideringsfejl.

5.3.3      Mangelfuldt datagrundlag

Datagrundlaget kan i nogle tilfælde mangle værdier som er påkrævet af wsdl skemaet, hvis dette er tilfældet vil felterne udfyldes med en erstatningsværdi.

...

5.3.4      Fejlfyldt CPR-data

Udover ovenstående erstatningsværdier kan der også være tale om data, som ikke har kunnet indlæses pga. fejlfyldt kildedata. Det kan fx være en dato, der ikke har kunne parses. Hvis der laves opslag på en person, som har fejlfyldt data vil der blive indsat erstatningsværdier for de felter, der er markeret som fejlfyldte eller der vil blive sendt en soap-fejl med beskeden ”Data for personen er markeret som upålideligt”. 

Hvorvidt der kommer en fejl eller der anvendes erstatningsværdier og hvad disse vil være sat til, afhænger af konfigurationen, se mere på http://www.nspop.dk

5.3.5      Navne- og adressebeskyttelse

For CPR-opslag gælder det generelt, at hvis en record i CPR-registret er markeret med navne- og adressebeskyttelse, da vil output være beskyttet ud fra følgende regler:

...

Hvorvidt en person er adressebeskyttet kan i svaret bestemmes ud fra ”PersonInformationProtectionIndicator” uanset om output er beskyttet eller læsbart.

5.4     CPR-registret: getPersonDetails

Stamdataservicen udstiller endvidere en variant af ’Det Gode CPR-opslag’, der kan anvendes til søgninger i CPR-registret med følgende input.

...

Servicen tager hensyn til navnebeskyttelse, og det anbefales at undersøge elementet PersonInformationProtectionIndicator for om værdien er true, da personen i så fald er navnebeskyttet.

5.4.1      Endpoints

På samme måde som DetGodeCprOpslag findes der to endpoints:

...

Det anbefales man anvender StamdataPersonLookup-1.0.1 i nye projekter, wsdl-filerne til denne kan findes i PERSONLOOKUP_1.0.1-mappen.

5.4.2      Mangelfuld data og fejlfyldt CPR-data

Se 5.3.3: Mangelfuldt datagrundlag og 5.3.4: Fejlfyldt CPR-data

5.4.3      Eksempel 1: getPersonDetails(<Personnummer>)

I denne variant af getPersonDetails søges på et specifikt CPR-nummer. Findes personen i CPR-registret, returneres de tilhørende CPR-informationer. Findes personen ikke i CPR-registret, returneres et tomt svar.

...

<stam:PersonLookupResponse />

5.4.4      Kald 2: (Opslag vha. navn)

getPersonDetails understøtter også søgninger på personnavn. Svar ved kald til denne variant er strukturelt identiske med svar ved søgninger på CPR-nummer eller liste af CPR-numre, og der henvises til disse eksempler for svarmuligheder.

...

Angives mellemnavnet ikke, ignoreres det og records med matchende for- og efternavn returneres. Se kaldet med en liste af CPR-numre for at se scenariet, hvor flere personelementer returneres.

5.4.5      Kald 3: (Opslag vha. fødselsdato)

getPersonDetails understøtter også søgninger på fødselsdato. Svar ved kald til denne variant er strukturelt identiske med svar ved søgninger på CPR-nummer eller liste af CPR-numre, og der henvises til disse eksempler for svarmuligheder:

<stam:PersonLookupRequest>
    <BirthDatePersonQuery>1991-09-22</BirthDatePersonQuery>
</stam:PersonLookupRequest>       

5.4.6      Kald 4: (Opslag vha. en liste af CPR-numre)

getPersonDetails understøtter også søgninger med en liste af CPR-numre som input. For hvert CPR-nummer på listen returneres CPR.informationerne eller et tomt svar, hvis CPR-nummeret ikke findes.

...

<stam:PersonLookupResponse>
  <ns:PersonInformationStructure>
    …
    <ns:PersonCivilRegistrationIdentifier>
      1111111111
    </ns:PersonCivilRegistrationIdentifier>
    …
  </ns:PersonInformationStructure>
  <ns:PersonInformationStructure>
    …
    <ns:PersonCivilRegistrationIdentifier>
      3333333333
    </ns:PersonCivilRegistrationIdentifier>
    …
  </ns:PersonInformationStructure>
</stam:PersonLookupResponse> 

5.5     CPR-Abonnementsservice

Stamdata tilbyder mulighed for at man for en liste af CPR-numre kan abonnere på ændringer i CPR-registret. Brugen af abonnementsservicen er skarpt opdelt i to snitflader:

...

Detaljeret information om indholdet af forespørgsler og svar for de enkelte kald findes i de følgende afsnit.

5.5.1      Vedligehold af abonnementslisten

Tilføjelse eller sletning af et CPR-nummer på abonnementslisten håndteres ved et kald til GOS med et request, hvor payload overholder dette skema:

...

<src-root-til-Behandlingsrelations-servicen>/doc/gos/Guide til Anvendere.docx

5.5.2      Udtræk af ændringer i CPR-data

Der findes to metoder til at få ændringer i CPR-data for  CPR-numrene på abonnementslisten:

...

<CprAbbsResponse xmlns==”http://nsi.dk/cprabbs/2011/10”>
    <changedCprs>1234567890</cpr>
    <changedCprs>2345678901</cpr>
</CprAbbsResponse>

6      Ændringslog

Kilden til dette dokument kan fås ved henvendelse til NSP-operatøren.

...

Bilag A: Eksempel på kald til abonnementsservicen

Nedenfor ses et eksempel på et kald til abonnementsservicen og det tilhørende svar. Eksemplet indeholder komplette headers, inklusiv IDkort, dog er signaturen og certifikatet erstattet med ”[...]”.

...