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 1 , 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:
Felt | Værdimængde |
---|---|
Gender.Value | male, female, other, unknown |
Address.Use | home,
|
Address.Type |
|
Contact.Use | mobile, home, work, temp |
Contact.System | phone,
|
Name.Use | official,
|
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:
Værdi | Beskrivelse |
---|---|
0 | Ukendt / ikke angivet |
1 | Oplyst af patient |
2 | Dokumenteret af patient, f.eks. ved at det blå europæiske sundhedskort eller pas er vist |
4 | Dokumenteret af sundhedsfaglig, f.eks. ved at der er modtaget en henvisning af en færøsk patient |
8 | Systemmæssigt valideret, f.eks. ved at det blå europæiske sundhedskort er læst maskinelt |
16 | Rapporteret fra kildesystem, uanset om der er tale om et X-eCPR eller D-eCPR |
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).
GetPermissions | Hent rettigheder for den pågældende bruger. |
GetOIDs | Hentning af OID-stamdata for alle OID brugt i Nationalt eCPR. |
GetPersonById | Opslag på personregistreringer via en Identifier, fx X-eCPR, pasnummer etc. |
SearchPerson | Søgning på personregistreringer via et query, fx navn OG køn OG fødselsdag |
CreatePerson | Oprettelse af en personregistrering (oprettelse af et X-eCPR) |
UpdatePerson | Opdatering af en personregistrering |
MergePersons | Fletning af to personregistreringer (sammenkobling af to X-eCPR) |
DeletePerson |
Sletning af personregistrering KUN I TEST |
ReservePersonId | Reservation af X-eCPR nummer |
CompareName | Sammenligning af et givent navn med navn på en personregistrering |
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 2 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:
-
SystemOwnerName
-
SystemName
-
SystemVersion
-
OrgResponsibleName
-
OrgUsingName
-
OrgUsingID
-
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.
Navn | sdsd:SystemOwnerName |
---|---|
Type | xs:string |
Værdisæt | Udfaldsrummet dikteres via det Centrale Virksomheds Register |
Eksempel | <SystemOwnerName>Pharma</SystemOwnerName> |
4.3. SystemName
SystemName elementet indeholder navnet på afsendersystemet.
Navn | sdsd:SystemName |
---|---|
Type | xs:string |
Værdisæt | Udfaldsrummet dikteres alene af leverandøren af afsendersystemet |
Eksempel | <SystemName>Medicinmodulet</SystemName> |
4.4. SystemVersion
SystemVersion elementet indeholder versionen på afsendersystemet.
Navn | sdsd:SystemVersion |
---|---|
Type | xs:string |
Værdisæt | Udfaldsrummet dikteres alene af leverandøren af afsendersystemet |
Eksempel | <SystemVersion>1.0</SystemVersion> |
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.
Navn | sdsd:OrgResponsibleName |
---|---|
Type | xs:string |
Eksempel | <OrgResponsibleName>Region Midt</OrgResponsibleName> |
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.
Navn | sdsd:OrgUsingName |
---|---|
Type | xs:string |
Værdisæt | Udfaldsrummet dikteres af den i OrgUsingID anvendte klassifikation |
Eksempel | <OrgUsingName>ROS Infektionsmedicinsk Amb.</OrgUsingName> |
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
Navn | sdsd:OrgUsingID |
---|---|
Type | xs:string |
Eksempel | <OrgUsingID NameFormat=“medcom:ynumber”>400777</OrgUsingID> |
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.
System | Identifier |
---|---|
Regionalt EPJ system | SKS, 6 eller 7 ciffer. Nogle regioner har selv opfundet 8. og 9. ciffer. Disse ekstra ciffer ignoreres af eCPR og kun de første 7 anvendes. |
Privatklinik med SKS kode | SKS, 6 eller 7 ciffer. |
LPS Ydernummer | valideres op imod yderregisteret |
LPS uden Ydernummer | SOR Id |
Vagtlæge systemer | SOR Id |
Kommunalt EOJ | SOR Id |
Regionalt EOJ | SOR Id |
Privatejet EOJ | SOR Id |
Tandlægesystemer | Ydernummer, der valideres op imod yderregisteret. For klinikker uden ydernummer anvendes CVR, der valideres op imod det anvendte certifikat. |
Apoteker systemer | EAN Lokationsnummer, valideres op mod SOR |
Kommunalt bostedssystem | SOR Id |
Regionalt bostedssystem | SOR Id |
Special klinikker uden yder eller SKS | SOR Id |
Systemkald, regional PAS systemer | SKS, 4, 6 eller 7 ciffer. |
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.
Navn | sdsd:OrgUsingID@NameFormat |
---|---|
Type | xs:string |
Format | ”medcom:ynumber”: Yderregisteret |
”medcom:pnumber”: CVR-P nummer | |
”medcom:skscode”: SHAK kode | |
”medcom:cvrnumber”: CVR nummer | |
”medcom:communalnumber”: Kommunekode | |
”medcom:sor”: SOR kode | |
”medcom:locationnumber”: EAN Lokationsnummer | |
Eksempel | <OrgUsingID NameFormat=“medcom:skscode”>650402</OrgUsingID> |
4.8. RequestedRole
RequestedRole elementet er beskrevet i afsnittet eCPR - Roller og rettigheder, sammen med rettigheder for de enkelte roller.
Navn | sdsd:RequestedRole |
---|---|
Type | xs:string |
Værdisæt | RequestedRole elementet er beskrevet i afsnittet eCPR - Roller og rettigheder. |
Eksempel | <RequestedRole>Læge</RequestedRole> |
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).
- Servicen kan kun anvendes i Test til at slette fejlagtigt oprettede person-registreringer. ↩
- WhitelistingHeader følger FMK standard. Det betyder ikke at det er nødvendigt at få whitelistet en løsning op mod Nationalt eCPR. ↩
Ændringslog
1.0 | 2023-11-07 | Side publiceret | SDS |
1.1 | 2023-11-13 | Tilføjet beskrivelse af historik | SDS |
1.2 | 2023-12-06 | Tilføjet afsnit om SOAP headers | SDS |