Differences

This shows you the differences between two versions of the page.

--- fmk:ecpr:1.0:ecpr_snitflade [2023-11-28 08:39] – maa
+++ fmk:ecpr:1.0:ecpr_snitflade [2024-04-23 11:53] (current) – removed maa
@@ Line 1: / Line 1: @@
-[[fmk:ecpr:1.0:ecpr|« eCPR2]]
-====== eCPR2 snitflade ======
-===== Generelt =====
-eCPR2 er en service til vedligehold af erstatningsCPR-numre og andre person-IDer samt relateret personstamdata, bla. køn, fødselsdag, adresser, kontaktoplysninger mm. I det følgende beskrives datamodellen samt hvordan data vedligeholdes via en række tilknyttede services.
-Modellen 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.
-De beskrevne services er pt. tilgængelige via DGWS. I følgende beskrivelse er sikkerhed for simpelhedens skyld udeladt.
-De konkrete WSDLer i {{ :fmk:ecpr:1.0:ecpr2-schemas.zip |}} i wsdl/ecpr2_dgws_service_2017_10_01.wsdl og OID-stamdata (GetOIDs) i wsdl/ecpr2_masterdata_2017_10_01.wsdl. wsdl'er med hardkodet PortType mod et miljø ligger i deres respektive undermappe (test1, test2, udd, prodtest, stage, prod)
-Servicen er tilgængelig i følgende miljøer
-**Test1**
-http://test1-cnsp.ekstern-test.nspop.dk:8080/decoupling/ecpr2/
-**Test2**
-http://test2-cnsp.ekstern-test.nspop.dk:8080/decoupling/ecpr2/
-**Prodtest**
-http://prodtest-cnsp.ekstern-test.nspop.dk:8080/decoupling/ecpr2/
-**Udd**
-http://uddannelse-cnsp.ekstern-test.nspop.dk:8080/decoupling/ecpr2/
-**Stage**
-https://stage-ecpr2.fmk.netic.dk/ecpr2/services/ecpr2
-**Prod**
-https://prod-ecpr2.fmk.netic.dk/ecpr2/services/ecpr2
-===== Begreber =====
-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". Hvert tal i en OID beskriver domænet - fx således for OIDen hørende til CPR-numre:
-(iso) 2 (member-body) 208 (dk) 176 (nsi) 1 (registries) 2 (cpr)
-Officielle OIDer kan findes beskrevet på oidref.org, fx http://www.oid-info.com/cgi-bin/display?tree=1.2.208.176.1.6 De understøttede OIDer kan trækkes via operationen getOIDs, som er beskrevet længere nede.
-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: [[fmk:ecpr:1.0:definition|eCPR Definitioner]]
-En person kan have en eller flere Identifiers, som benyttes når man i et request udpeger hvilken person der skal opdateres. Dette gøres via en "KeyIdentifier"-struktur, hvor man angiver OID og værdi som her:
-<code xml>
-<KeyIdentifier>
-  <OID>1.2.208.176.1.6.1.1</ns2:OID>
-  <Value>1212701XG7</ns2:Value>
-</ns2:KeyIdentifier>
-</code>
-En person kan have tilknyttet et antal adresser, navne, kontaktoplysninger og et køn. Når man først har oprettet en entitet (adresse/kontaktoplysning osv), bliver den tildelt en PID, som returneres ifm. opslag på data. Denne PID skal benyttes hvis data skal redigeres eller slettes.
-Når man udfører en opdaterende operation, skal man angive hvem der foretager opdateringen. I historikken vil man eftergølgende kunne se, hvem der står bag en opdatering. Dette angives i en Modifier-struktur på denne måde:
-<code xml>
-<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>
-</code>
-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.
-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
-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 konkatenering 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.
-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)
-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. OBS! Snitfladen understøtter parametre (fx "nickname"), som ikke må anvendes. Disse er markeret med gennemstregning i tabellen. Parametrene vil muligvis blive fjernet i fremtidige snitflade versioner. Det drejer sig om:
-^ Felt ^ Værdimængde ^
-|Gender.Value|male, female, other, unknown|
-|Address.Use|home, <del>work, temp, old</del>|
-|Address.Type|<del>postal, physical,</del> both|
-|Contact.Use|mobile, home, work, temp|
-|Contact.System|phone, <del>email, sms, fax, pager, url, other</del>|
-|Name.Use|official, <del>usual, nickname, maiden, old</del>|
-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|
-===== WSDL =====
-Der findes en række services i eCPR2, som er defineret gennem to WSDLer:
-  * **ECPR2Service**: De basale service til opslag og opdatering af data
-  * **ECPR2MasterDataService**: Utility service til OID-opslag
-De konkrete WSDLer findes i {{ :fmk:ecpr:1.0:ecpr2-wsdl.zip |}} under /wsdl.
-===== Serviceoperationer =====
-Nedenfor beskrives de forskellige operationer i de 2 WSDLer. For hver operation gives eksempler på request/response (for simpelhedens skyld uden DGWS/IDWS headers). Eksemplerne tjener dels til formål at give overblik over hvad der skal til for at bruge en operation, men demonstrerer samtidigt hvilke elementer der er krævet.
-^ Operation ^ Beskrivelse ^
-| [[fmk:ecpr:1.0:getpermissions | GetPermissions]] | Hent rettigheder |
-| [[fmk:ecpr:1.0:getoids | GetOIDs]] | Hentning af OID-stamdata |
-| [[fmk:ecpr:1.0:getpersonbyid | GetPersonById]] | Opslag på person via Identifier |
-| [[fmk:ecpr:1.0:searchperson | SearchPerson]] | Søgning på personer |
-| [[fmk:ecpr:1.0:createperson | CreatePerson]] | Oprettelse af person |
-| [[fmk:ecpr:1.0:updateperson | UpdatePerson]] | Opdatering af person |
-| [[fmk:ecpr:1.0:mergepersons | MergePersons]] | Fletning af person-data |
-| [[fmk:ecpr:1.0:deleteperson | DeletePerson]] | Sletning af person (KUN TEST) |
-| [[fmk:ecpr:1.0:reservepersonid | ReservePersonId]] | Reservation af erstatnings-CPR |
-| [[fmk:ecpr:1.0:comparename | CompareName]] | Sammenligning af navn med navn på person |
-Der findes eksempler på requests og responses i [[https://www.nspop.dk/download/attachments/226764158/xml-samples.zip|xml-samples.zip]] (bemærk dog, at SOAP-headers er udeladt for simpelheds skyld).
-===== 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:
-<code xml>
-<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>
-</code>