Indholdsfortegnelse:

1. Indledning

Nationalt eCPR udstiller eCPR2-servicen, som er en service til vedligehold af Nationale eCPR-numre, tilhørende personregistreringer inkl. andre person-IDer og relateret personstamdata såsom køn, fødselsdag, adresser, kontaktoplysninger mm. 

Datamodellen for Nationalt eCPR gør brug af forskellige OIO- og HL7 FHIR-begreber ifm. hvilke adressetyper, kontaktoplysninger osv. der findes. Modellen kræver dog ikke indgående HL7-kendskab.

Det centrale i modellen er en “Person”, som identificeres via en eller flere “Identifier”-strukturer. En Identifier er en værdi samt hvilket “domæne” værdien tilhører. Et domæne identificeres via en “OID” (object identifier), som er en hierarkisk nøgle. Fx hører CPR-numre til OID “1.2.208.176.1.2”.

Der genereres en Identifier for en Person med OID “1.2.208.176.1.6.1.1” (X-eCPR)

Strukturen af eCPR numre kan læses her: eCPR - Formater (X-eCPR og D-eCPR)

I dette dokument gennemgås snitfladen til eCPR2-servicen.

2. Datamodel

Hele modellen (med multipliciteter) ses her:

Person
  Identifier 0-*
    PID 1
    OID 1 (domæne og type f.eks 1.2.208.176.1.6.1.1)
    OIDLabel 1 (tekst svarende til OID, f.eks. ”X-eCPR”)
    OIDType 1 (tekst svarende til typen af OID'en, f.eks. "eCPR-nummer")
    Value 1 (f.eks. 0908167MM1)
    Validity 0-1 (validitet, f.eks. 16)
    Expiry 0-1 (eventuel kendt udløbsdato)
    ValidFrom 1
    ValidTo 0-1
  Name 0-*
    PID 1
    Use 1 (official)
    Text 0-1 (tekstrepræsentation af det fulde navn)
    FamilyName 0-1 (efternavn)
    GivenName 0-1 (fornavn)
    Expiry 0
    ValidFrom 1
    ValidTo 0-1
  Gender 0-(*)
    PID 1
    Value 1 (male, female, other, unknown)
    ValidFrom 1
    ValidTo 0-1
  BirthDate 0-(*)
    PID 1
    Value 1 (f.eks. 2004-11-27, 2004-11 eller 2004)
    ValidFrom 1
    ValidTo 0-1
  Contact 0-*
    PID 1
    System 0-1 (phone)
    Use 0-1 (home, work, temp, ...)
    Value 1
    Expiry 0-1 (eventuel kendt udløbsdato)
    ValidFrom 1
    ValidTo 0-1
  Address 0-*
    PID 1
    Use 1 (home)
    Type 1 (both)
    Text 0-1 (tekstrepræsentation af adressen, kun udfyldt og tilladt i response)
    Line 0-10 (adresslinjer, max 10 stk. er tilladt)
    City 0-1
    District 0-1
    State 0-1
    PostalCode 0-1
    Country 0-1 (ISO 3166 landekode)
    CountryName 0-1 (landenavn på Dansk)
    PostBox 0-1
    Expiry 0-1 (eventuel kendt udløbsdato)
    ValidFrom 1
    ValidTo 0-1
  Modified 0-(*)
    By 1
      Person 1 (hvem der sidst har oprettet eller ændret)
        AuthorisationIdentifier 0-1
        Name 1
        PersonIdentifier 1
          PersonIdentifier 1
          Source 1
        SpecialityCode 0-1
      Role 1 (hvilken rolle personen havde, da oprettelsen eller ændringen skete)
      Organisation 1 (hvilken organisation opretteren eller ændreren arbejdede for)
        Name 1
        AddressLine 0-1
        TelephoneNumber 0-1
        EmailAddress 0-1
        Type 1
        Identifier 1
          Identifier 1
          Source 1
      AuthorisedBy 0-1 (hvem der har autoriseret personen til at foretage oprettelsen eller ændringen)
        Person 1
          AuthorisationIdentifier 0-1
          Name 1
          PersonIdentifier 0-1
            Identifier 1
            Source 1
          SpecialityCode 0-1
        Organisation 1
          Name 1
          AddressLine 0-1
          TelephoneNumber 0-1
          EmailAddress 0-1
          Type 1
          Identifier 1
            Identifier 1
            Source 1
    ReservedUntil 0-1 (Angiver person-id er reserveret og tidsp. reserveret til)
    ValidFrom 1 (dato og tid versionen af oprettet)
    ValidTo 0-1 (dato og tid versionen er gældende til)

En grafisk repræsentation og yderligere gennemgang af datamodellen kan ses her.

2.1. Identifier

En personregistrering kan have en eller flere Identifiers. En identifier er unikke id'er. En personregistrering vil altid som minimum have et Nationalt eCPR-nummer (X-eCPR), men der kan være flere identifiertyper tilknyttet.

• CPR-nummer
• Decentralt eCPR-nummer
• Pas-nummer
• Kørekort-nummer
• Asylansøger Person-ID
• Sundhedskortnummer

For alle disse identifiers gælder det, at det samme kombination af type og værdi ikke kan være registreret som en valid værdi på mere end én personregistrering ad gangen.

Dvs. at servicen validerer at det samme danske pas ikke kan registreres på to forskellige personregistreringer, med mindre den ene registrering er historisk (ValidTo er sat).

Det gælder også, at en personregistrering ikke kan have flere aktive elementer af den samme type.

Dvs. at servicen validerer at der ikke kan registreres to danske pas på den samme personregistrering, med mindre den ene registrering er historisk (ValidTo er sat).

2.2. Elementers PID

En person kan have tilknyttet et antal adresser, navne, kontaktoplysninger og et køn. Når man først har oprettet et dataelement (fx en adresse/kontaktoplysning osv), bliver den tildelt en PID, som returneres ifm. opslag på data. Denne PID skal benyttes, hvis data skal redigeres eller slettes.

2.3. Modified By

Når man udfører en opdaterende operation, skal man angive hvem der foretager opdateringen. Dette angives i en Modifier-struktur på denne måde:

<Modified>
  <By>
    <Person>
      <AuthorisationIdentifier>AB01C</AuthorisationIdentifier>
      <Name>Jens Jensen</Name>
      <PersonIdentifier>1234567890</PersonIdentifier>
    </Person>
    <Role>Læge</Role>
    <Organisation>
      <Name>Andeby hospital</Name>
      <Type>Hospital</Type>
      <Identifier>
        <Identifier>1234123412</Identifier>
        <Source>SOR</Source>
      </Identifier>
    </Organisation>
  </By>
</Modified>

Når man henter en personregistrering, returneres både de nuværende oplysninger på personregistreringen, og hele historikken inkl. udløbne og ikke-valide (opdaterede eller slettede) oplysninger. 

Derudover får man en liste af Modified-elementer, som hver har en ValidFrom/ValidTo og en By. Dvs. at man i historikken efterfølgende vil kunne se, hvem der står bag en opdatering. 

I de tilfælde hvor ValidFrom i Modified passer på en ValidFrom i et dataelement, er det den Modified By der har oprettet det element. OBS! Det kan være oprettet som en opdatering til en eksisterende værdi. 

I de tilfælde hvor ValidFrom i Modified passer på en ValidTo i et dataelement er det den Modified By der har sat det element til historisk (invalideret data).

2.4. Historik

Nationalt eCPR har fuld historik på samtlige ændringer. Historik håndteres ved, at der på samtlige overordnede dataelementer (navn, adresse, id’er osv.) findes et datointerval hvor registreringen er aktuel fra, givet ved en validFrom-dato. Er registreringen ikke længere aktuel findes der en validTo-dato, der angiver, hvornår registreringen ikke længere er aktuel.

Dataelementerne for id’er, navn, kontaktinformation og adresse kan desuden have en forretningsmæssig udløbsdato (Expiry). Dvs. det kan angives hvornår f.eks. et pas udløber, hvornår personen ikke længere kan kontaktes på en adresse m.v. 

Samtlige historiske dataelementer er søgbare. Det er således også muligt at fremsøge f.eks. på et udløbet pasnummer eller en tidligere adresse. 

Der findes en enkelt undtagelse fra ovenstående beskrivelse; operationen DeletePerson ¹ , der sletter samtlige registreringer på personen, aktuelle og historiske.

2.4.1. ValidFrom/ValidTo

Når en opdatering er gennemført, vil de berørte data have et “ValidFrom”-element lig med tidspunktet hvor opdateringen skete. Hvis der sker efterfølgende opdateringer, vil den tidligere entitet beholdes, men får et “ValidTo”-element der angiver hvornår pågældende data ikke længere er gyldige, og der findes en ny modifier, som ikke har en “ValidTo”-værdi. Dvs. aktuelle værdier kendetegnes ved ikke at have ValidTo, og historiske værdier har ValidTo. Man kan betegne ValidFrom/ValidTo som en teknisk gyldighedsperiode. På Identifier, Name, Contact og Address kan man desuden angive en forretningsmæssig gyldighed via en “Expiry”-dato, som fx kan være udløbsdato for et EU-sundhedskort. Hvis Expiry er udløbet på opslagstidspunktet, vil denne dato stå som ValidTo, og elementet anses ikke længere som gyldigt.

ValidFrom, ValidTo, PID, OID, PrimaryOIDLabel og SecondaryOIDLabel har samme betydning på alle entiteter.

2.4.2. Expiry

Det er muligt at angive Expiry med varierende præcision i request. Der gælder følgende regler for, hvordan datoer med “lavere præcision” fortolkes:

yyyy-mm-dd hh:mm → yyyy-mm-dd hh:mm:00
yyyy-mm-dd hh → yyyy-mm-dd hh:00:00
yyyy-mm-dd → yyyy-mm-dd 00:00:00
yyyy-mm → yyyy-mm-01 00:00:00
yyyy → yyyy-01-01 00:00:00
tomt → xxxx-01-01 00:00:00
hvor xxxx er året Expiry-elementet oprettes

2.5. Begrænsede feltværdier

Det gælder for visse felter, at der er en begrænset tilladt værdimængde. Det håndhæves ikke via WSDL/XSD, men via simpel validering i de forskellige services. Det drejer sig om:

OBS! Snitfladen understøtter parametre (fx “nickname”), som ikke må anvendes. Disse er markeret med gennemstregning i tabellen. De gennemstregede parametre vil muligvis blive fjernet i fremtidige snitflade versioner.

2.6. Response Only værdier

I modellen findes der en række felter, som kun bliver udfyldt i responses. Det drejer sig om:

• PrimaryOIDLabel: En tekstuel beskrivelse af OIDens domæne

• SecondaryOIDLabel: En eventuelt fortsættende beskrivelse af OIDens domæne

• OIDType: En tekstuel beskrivelse af OIDens type

• Name.Text: Simpel konkatinering af fornavn og efternavn

• Address.CountryName: Landets navn (på dansk)

• ValidFrom: Gyldig fra. System-genereret, kan ikke sættes af klient

• ValidTo: Gyldig til. System-genereret, kan ikke sættes af klient

Hvis ovenstående værdier angives i requests, vil der returneres en fejl.

2.7. Validitet

Identifier.Validity angiver ”troværdigheden” eller ”sikkerheden” af værdien. Validiteten kan f.eks. anvendes til at vurdere hvorvidt f.eks. et EHIC-nummer (nummer på det blå europæiske sygesikringskort) er tilstrækkeligt troværdigt til at en aktør manuelt vil flette to registreringer baseret på denne registrering. Der kan anvendes følgende værdier:

3. Operationsliste

Nedenfor findes en liste over de forskellige operationer i eCPR2 servicen. For hver operation linkes til en side med yderligere uddybning og eksempler på request/response (for simpelhedens skyld uden DGWS/IDWS headers). 

Der findes eksempler på requests og responses i xml-samples.zip (bemærk dog, at SOAP-headers er udeladt for simpelheds skyld).

3.1. KeyIdentifier

I operationerne GetPersonById, UpdatePerson, DeletePerson og CompareName identificeres personregistreringen med en “KeyIdentifier”-struktur, hvor man angiver OID og værdi som her:

<KeyIdentifier>
  <OID>1.2.208.176.1.6.1.1</ns2:OID>
  <Value>1212701XG7</ns2:Value>
</ns2:KeyIdentifier>

4. SOAP Headers

I Nationale eCPR-servicen foretages skal der tilføjes SOAP header blocks, der unikt identificerer det software, der ønsker at kalde løsningen. Bemærk at denne identifikation ikke er en del af ID kortet, men implementeres som selvstændige XML-elementer i SOAP headeren indkapslet i et WhitelistingHeader ² element. Det er derfor ikke bundet til en session, men kan variere fra en forespørgsel til næste.

Headeren er tænkt som en udvidelse af MedCom - Den gode Webservice, og er under standardisering i SDS regi.

Der tilføjes et WhitelistingHeader element med flg. XML elementer til SOAP headeren. Alle er af type xs:string:

1. SystemOwnerName

2. SystemName

3. SystemVersion

4. OrgResponsibleName

5. OrgUsingName

6. OrgUsingID

7. RequestedRole

4.1. Eksempel

Nedenstående eksempel er en typisk WhitelistingHeader for et regionalt system.

<soapenv:Envelope 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sdsd="http://www.sdsd.dk/dgws/2010/08" 
  xmlns:sdsd20120601="http://www.sdsd.dk/dgws/2012/06"
  xmlns:medcom="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <soapenv:Header>
    <sdsd201206:WhitelistingHeader>
      <sdsd:SystemOwnerName>Leverandør A</sdsd:SystemOwnerName>
      <sdsd:SystemName>System A</sdsd:SystemName>
      <sdsd:SystemVersion>1.5</sdsd:SystemVersion>
      <sdsd:OrgResponsibleName>ROS IT-afdeling</sdsd:OrgResponsibleName>
      <sdsd:OrgUsingName>Alb Plastikkirurgisk Dagafdeling</sdsd:OrgUsingName>
      <sdsd:OrgUsingID NameFormat="medcom:skscode">8001506</sdsd:OrgUsingID>
      <sdsd:RequestedRole>Læge</sdsd:RequestedRole>
    </sdsd201206:WhitelistingHeader>
    <!-- ... -->
  </soapenv:Header>
  <soapenv:Body>
    <!-- ... -->
  </soapenv:Body>
</soapenv:Envelope>

4.2. SystemOwnerName

SystemOwnerName elementet indeholder det entydige navn på leverandøren af afsendersystemet.

4.3. SystemName

SystemName elementet indeholder navnet på afsendersystemet.

4.4. SystemVersion

SystemVersion elementet indeholder versionen på afsendersystemet.

4.5. OrgResponsibleName

OrgResponsibleName indeholder det entydige navn på den organisation, der har ansvaret for it-systemet. Dette bør svare til den sundhedsfaglige organisations registrering i CVR. 

4.6. OrgUsingName

OrgUsingName indeholder det entydige navn på den sundhedsfaglige organisation, der benytter it-systemet. Det bemærkes, at organisationen meget vel ikke kan identificeres via en klassifikation som CVR, som f.eks. en Fælles Akut Modtagelse i en region. Derfor anvendes der ikke klassifikationer for denne attribut. OrgUsingName er entydig. 

4.7. OrgUsingID

OrgUsingID indeholder det entydige id på den organisation, hvor brugeren aktuelt befinder sig når webservice kaldet udføres. Klassifikationen hvortil id’et hører er angivet i attributten OrgUsingID@NameFormat og headeren OrgUsingName angiver navnet på organisationen hørende til id’et. De typer der supporteres af Nationalt eCPR er de samme som supporteres i FMK og er dokumenteret på Organisationskoder i FMK

4.7.1. OrgUsingID Identifier

Nedenstående tabel angiver hvilken type OrgUsingID, der skal anvendes for de forskellig typer systemer. Såfremt der er systemer, der ikke er angivet i nedenstående tabel, kan man lave en supportsag på NSPOP for at få afklaret hvilken type der skal anvendes. 

Nationalt eCPR følger FMK i brugen af SOR.

4.7.2. OrgUsingID@NameFormat

Klassifikationssættet i attributten OrgUsingID@NameFormat angiver den klassifikation, som attributterne OrgUsingID og OrgUsingName henter sine værdier fra. Bemærk at attributten skal anvendes i XML dokumenter uden namespace prefix, selvom det selvfølgelig er defineret i et namespace.

4.8. RequestedRole

RequestedRole elementet er beskrevet i afsnittet eCPR - Roller og rettigheder, sammen med rettigheder for de enkelte roller.

5. Fejlhåndtering

Hvis en service modtager data der ikke opfylder krav til fx format, vil der returneres en fejl. Alle logiske fejl returneres på dansk som “faultstring” i SOAP Fault. Det kan fx se således ud, hvis man ikke overholder datoformatet for fødselsdag:

<Envelope>
  <Header>
  </Header>
  <Body>
    <Fault>
      <faultcode>Server</faultcode>
      <faultstring xml:lang="en">
        Fejl i request ifm. med opdatering af eCPR-data, Ulovligt format for fødselsdag (ÅÅÅÅ-MM-DD): [2020-04-130]
      </faultstring>
    </Fault>
  </Body>
</Envelope>

5.1. Header fejl

Hvis en af de krævede elementer mangler i headeren, eller det kaldende system ikke er autoriseret til at kalde eCPR, returneres en SOAP fault med fejlkode 4300 (Manglende system autorisation).

---

1. Servicen kan kun anvendes i Test til at slette fejlagtigt oprettede person-registreringer.  ↩
2. WhitelistingHeader følger FMK standard. Det betyder ikke at det er nødvendigt at få whitelistet en løsning op mod Nationalt eCPR. ↩

---

Ændringslog