...

Dokument målrettet systemadministratorer og driftspersoner, som skal kunne håndtere driftsmæssige aspekter af komponenten. Driftsvejledningen skal indeholde information om komponentens version, standard placering af logfiler og konfigurationsfiler, eksterne afhængigheder, og evt. krav til genstart af applikationer hvis komponenten bliver ikke-responsiv. Start/stop vejledning for komponenten beskrives, herunder hvilke andre applikationer der evt. skal genstartes. Kendte fejlkoder som skrives i logfiler dokumenteres, så disse evt. kan overvåges, og tillige danne baggrund for fejlsøgning. En generel læsevejledning til logfiler vedlægges. Det bør angives hvorledes komponenten bedst lader sig overvåge, dvs. en generisk beskrivelse af overvågningen, der ikke er værktøjsafhængig. Evt. specielle krav til backup beskrives, ligesom procedure ved reetablering af komponenten ud fra backup beskrives.

2     

...

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:

...

Parameter

...

Beskrivelse

...

Eksempel

...

Register

...

Det register, der ønskes udtræk fra.

...

”CPR”

...

Datatype

...

Hvert register er opdelt i en række datatyper, og et kald til KRS returnerer en enkelt af disse.

...

”person”

...

Versionsnummer

...

Af hensyn til bagud­kompabilitet versioneres udtræks­funktionaliteten for hvert enkelt register

...

”V1”

...

Offset

...

En parameter, der angiver hvorfra i servicens udtræk af ændrede data svaret skal påbegyndes.

...

”1024”

...

MaxRowCount

...

Det maksimalt antal returnerede rækker. Anvendes til at styre størrelsen af svarene fra KRS.

...

”512”

Omfattede komponenter

Dette dokument omfatter driften af alle Stamdata importer komponenterne  

Listen herunder beskriver hver komponent med type status URL og navnet på filen som skal deployes. Status URL’en kan løbende polles for at checke komponentens status. Status sider er beskrevet mere detaljeret senere i dokumentet.

2.1     Stamdata importer komponenter

2.1.1  Stamdata Data Importere

Hver stamdata importer ligger i sin egen WAR fil, hver importer har sin egen overvågnings URL, der enten fortæller om den enkelte importer er operationsdygtig (HTTP 200 OK), eller om der er fejl i importeren (HTTP 500 ERROR), Overvågningssiden vil give et bud på hvad fejlen er, dog bør man kigge i log-filen for at få alle detaljer med.

 Type: Batch

• Status Url: http://<hostname>:<port>/<komponent-navn>/
• Filnavn: <komponent>.war

3      Opdatering til nye versioner

Når nye versioner af Stamdata komponenterne udkommer, vil der medfølge release notes som forklarer database-migrering, rollback-procedure, service vinduer mv. Til installation af første version af stamdata komponenterne henvises til installationsguiden.

4      Daglig Drift

4.1 Stamdata Importere

Stamdataimporterne er en gruppe filparsere og batch jobs som indlæser og vedligeholder data fra forskellige registre og gemmer dem i en MySQL database. Hver importer har sin egen inbox-mappe som automatisk oprettes når servicen startes. Roden for disse inboxmapper er:

 <JBOSS_HOME>/domain/data/sdm4/

 Komponenten kigger i sin inboxmappe for at se om der kommer nye filer til import. Det er driftens opgave at placere filer i inboxmapperne når tiden er inde for en opdatering. Hvilke filer der skal bruges og hvor ofte registrene skal opdateres er beskrevet i slutningen af dokumentet. Hver inbox er logisk navngivet efter den tilhørende importer. Se afsnittet om overvågning for monitorering af servicen

4.1.1      Fremgangsmåde for indlæsning af nye data

Parserne forventer data at blive lagt i undermapper af deres rod-mappe, f.eks.: 

<JBOSS_HOME>/domain/data/sdm4/<importer>/20120822T201121S231/<file.txt>

<JBOSS_HOME>/domain/data/sdm4/<importer>/20120822T201121S231/<file2.txt>

Undermappernes navne er underordnede. De importeres i leksikografisk orden, og det vil derfor være oplagt at lægge dem så undermappernes navne er tidsstempler som vist i eksemplet.

Skulle der ske en fejl under import, vil der blive lagt en fil ved navn

"LOCKED" i parserens inbox, f.eks.:

<JBOSS_HOME>/domain/data/sdm4/<importer>/LOCKED

Parseren vil ikke forsætte før denne fil er slettet manuelt. Fejl-beskeden kan findes i loggen.

4.1.2    Eksempel for import af nye CPR-data

Her en et eksempel på strukturen for en parsers filsystem. I dette tilfælde er det CPR-parseren:

<JBOSS_HOME>/domain/data/sdm4/cprimporter/

Placeres filen ’D100312.L431101’ (som er en typisk CPR Person fil) i inputmappen begynder parseren at stabilisere data. Man kan gå ind på komponentens monitoreringsside for at se status for import:

http://<hostname>:<port>/cprimporter/status

Her vil man kunne se om CPRimporteren kører, hvornår CPRimporteren sidst har kørt, og hvilken status den har.

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

3.4     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.:

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

Revisionsnummeret kan findes ved at kigge på entry-elementernes id-element. F.eks. i

tag:nsi.dk,2011:sor/apotek/v1/168763721800723

er 168763721800723 revisionsnummeret.

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

...