Version 1.0 Oktober 20121 September 2013

Introduktion

NSP´en udstiller en stamdata kopiregister service (SKRS). Servicen giver systemer mulighed for at holde / trække en lokal kopi af et nationalt stamdata registerdatasamlinger, som f.eks. CPRudtræk fra CPR-registeret eller SOR-registeret. 

For at få adgang til stamdatas kopi-register-service skal man først have oprettet en juridisk aftale ved at kontakte NSP-operatøren (se: Bestillingsark for stamdataregistre). Aftalen giver adgang til forskellige data fra de respektive registre. Præcist hvilke registre og data-typer man får adgang til er afhængigt af din aftale. Der er en liste over alle tilgængelige datasamlinger fra stamdata registre på : Komponenter på NSP platformenStamdataregistre.

Service beskrivelse

1.1     URI Format

Ressourcer (datatyper) er ordnet i et hierarkisk URI navnerum med URI skemanavnet stamdata.

stamdata://[register]/[view]/[version]?[query]

URI-autoriteten, markeret med teksten register, repræsenterer registeret hvor data kommer fra, f.eks. CPR-registeret.

Den resterende del af URI stien starter med en skråstreg '/' efterfulgt af navnet på den datatype (også kaldt view) man vil hente – markeret med teksten view – og hvilken version man ønsker, markeret med teksten version.

Til sidst tilføjes en række parametre, der specificerer hvor langt man er nået i et kopi-udtag og hvor mange records man ønsker at kopierer adgangen. Paginering bliver beskrevet i flere detaljer senere i dokumentet.

1.2     Stamdata protokollen

Stamdata er baseret på to forskellige teknologier DGWS/SOAP og REST. Første skridt i en samtale med stamdata er at få et autorisationstoken. Et token er en 512 bit nøgle som bruges som identifikation til alle efterfølgende kald. På den måde minder et token meget om et SOSI IDkort. Et token giver dig adgang til én data-type i et register. Hvis man vil hente forskellige datatyper skal du oprette et token for hver type. Et token er gyldigt lige så længe som det SOSI IDkort, der blev brugt til at oprette den med.

1.2.1      Forespørgsler til Token Servicen

For at hente et token skal man bruge tokenservicen. I dette afsnit er der en kort beskrivelse af hvordan man kommunikerer med Token Servicen (STS).

Når man vil hente et token skal man identificerer sig selv med et SOSI IDkort. DGWS er ikke beskrevet i detalje i dette dokument, men kan findes på http://www.medcom.dk/wm110731.

I SOAP-body sender man navnet på den datatype man vil hente. Datatypens navn består af en URI, f.eks. stamdata://cpr/person/v1 hvis man ønsker at hente person datatypen fra CPR registeret i version 1. Et token består af en lang streng som er base64 encoded.

1.2.2      Eksempel på kald til Token Servicen

Som klient sender man ’token request’ til token servicen:

<soapenv:Envelope

  xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/

  xmlns:ns="http://trifork.com/-/stamdata/3.0">

  <soapenv:Header>...</soapenv:Header>

  <soapenv:Body>

    <ns:AuthorizationRequestStructure>

      <ns:viewUri>stamdata://yderregisteret/yder/v1</ns:viewUri>

    </ns:AuthorizationRequestStructure>

  </soapenv:Body>

</soapenv:Envelope>

Headeren skal selvfølgelig indeholde DGWS 1.0.1 headers.

Hvis alt går som forventet og din forespørgsel bliver godkendt modtager man et svar i stil med følgende:

<soapenv:Envelope ...>

  <soapenv:Header>...</soapenv:Header>

  <soapenv:Body>

    <ns:AuthorizationResponseStructure>

    <ns:authorization>

      3247632398kjb32hg32yg32uytf2763t237gf237trf

      8gf8723g873gf8o374gr28o7723bor872t3fbcoa783

      29723yr7...

    </ns:authorization>

    </ns:AuthorizationResponseStructure>

  </soapenv:Body>

</soapenv:Envelope>

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

<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>

1.2.3      Forespørgsler til kopi-register-servicen

Når man har modtaget et token til en datatype, som beskrevet i foregående afsnit, kan man bruge det til at hente data fra kopi-register-servicen.

Stamdata Kopi Protocol is 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 registrer, eller nærmere bestemt, datatyperne i de registrer.

Når man laver et HTTP request til kopi-register-servicen skal man specificere tre ting:

1. Datatypen man vil hente opdateringer til, f.eks. sks/apotek/v1
2. Formatet man vil have data overført i, f.eks. application/atom+xml
3. Et token som man har hentet fra Token Servicen.

1.2.4      Eksempel på kald til kopi-register-servicen

GET /stamdata/sks/apotek/v1 HTTP/1.1

Host: example.com          

Accept: application/atom+xml

Authentication: STAMDATA f32hdh2dew2hd&67oqiwjdow33423j23j11gF41... 

Dette kald henter data fra sks/apotek/v1 datatypen. Datatypen er bestemt ud fra den path man sender i linje 1.

Man har her valgt at få data overført i ATOM format og sætter accept headeren til application/atom+xml (se linje 3).

I ’Authentication’-headeren skriver man ordet STAMDATA efterfulgt at den token man har fået fra token-servicen.

NB. Grunden til at man skal skrive STAMDATA er at det er et custom sikkerheds skema, da tokens ikke passer ind i HTTP–Basic eller –Digest skemaerne.

På nuværende tidspunkt understøtter servicen output med følgende formatter:

1. ATOM Feed i XML (application/atom+xml)
2. ATOM Feed i Fast Infoset (application/atom+fastinfoset)

Man skal angive en af disse to i Accept headeren.

1.2.5      Eksempel på kald til kopi-register-servicen (svaret)

Svaret på et kald til kopi-register servicen er en ATOM feed. Her er et response som kunne være svar på kaldet i Eksempel 1. Man kan bruge ethvert ATOM API til at parse det.

HTTP/1.1 200 OK 

<feed xmlns=”http://www.w3.org/2005/Atom”

  xmlns:sd="http://www.trifork.com/-/stamdata/3.0/sor"> 

  <id>tag:trifork.com,2011:sor/apotek/v1/1687637218007231</id>

  <title>Stamdata Update Feed: sor/apotek/v1</title>

  <updated>2010-12-13T18:30:02Z</updated>

  <author>

    <name>Trifork Stamdata</name>

    <email>support.stamdata@trifork.com</email>

  </author>

  <entry> 

    <id>tag:trifork.com,2011:sor/apotek/v1/1687637218007231</id>

    <title/> <!— title elements can be ignored -->

    <updated>2010-12-13T18:30:02Z</updated>

    <content type="application/xml">

      <sd:apotek>

        <id>7236A-23</sd:id>

        <name>Svane Apoteket</name>

        <eanLocation>21341231231223</eanLocation>

        ...                    

      </sd:apotek>

    </content>

  </entry> 

  <entry>

    <id>tag:trifork.com,2011:sor/apotek/v1/1787637218007236</id>

    <title/>

    <updated>2003-12-13T15:31:11Z</updated>

    <content type="application/xml">

      <sd:apotek>

      <id>2132121</id>

      <name>Svane Apoteket</name>

      <eanLocation>11341231231223</eanLocation>

      ...

      </sd:apotek>

    </content>

  </entry>

</feed>

Hvis vi havde sat Accept headeren til ’application/atom+fastinfoset’, havde output været i FastInfoset format men med samme struktur som i dette eksempel.

1.3     Parsing af output

Det mest interessante ved et response er ’entry’-elementerne. Hvert ’entry’-element indeholder et snapshot af en record fra registeret. 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 ’apotek’ som er indeholdt.

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

1.3.1      Unikke Nøgler

Hver view-type har et nøgleelement som unikt bestemmer en record. Et eksempel der er let at forstå, er CPR-regsiteret, hvor en person unikt bestemmes ved sit CPR-nummer. 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 views vil være beskrevet i listen over registre i dokumentet "Registerspecifikation for Anvendere”.

1.3.2      Versionsnummer

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

Versionsnummeret kan findes ved at kigge på entry-elementernes id-element. F.eks. i tag:trifork.com,2011:sor/apotek/v1/168763721800723 er 1687637218007236 versionsnummeret.

Med andre ord, bestemmer en unik nøgle en bestemt entitet, versionsnummeret 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 versionsnumre vil altid være forskellige.

1.4     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.

1.5     Respons koder for webservicen

Guide til anvendere

NSP-guide til anvendere findes i dokumentation for kopiregister service m.v. Guiden findes her: Guide til anvendere Stamdataregistre.docx

Øvrig Dokumentation

...