Page History
Besked format
Web servicen forventer SOAP beskeder. SOAP headeren indeholder sikkerheds header og Medcom header som krævet i DGWS 1.0.1. Udover dette skal der også være en HSUID header.
Navitabs | ||||
---|---|---|---|---|
| ||||
Table of Contents |
---|
Introduktion
Formål
Denne specifikation af snitfladen til administration af samtykke og spærringer beskriver de services, der leveres til henholdsvis sundhedsfalige og borgere, der ønsker at udføre administration (oprettelse, ændring, sletning) af samtykke eller spærring.
Koncepter
En MinSpærring registrering beskriver sammenhængen mellem:
...
En sundhedsfagligs adgang til følsom data for en specifik borger er ikke påvirket hvis den oprettede spærring eller samtykke er for en anden sundhedsfaglig eller organisation. Dette er f.eks. hvis der er oprettet en spærring for en anden sundhedsfaglig end den der forespørger på data.
Definitioner og referencer
Formålet med denne sektion er at give et overblik over definitioner og referencer anvendt i dette dokument.
...
Alias | Beskrivelse |
DGWS 1.0 | Den Gode Webservice 1.0 |
DGWS 1.0.1 | Den Gode Webservice 1.0.1 |
HSUID-header | Healthcare Service User Identification Header (SSE/11734/IFS/0018) |
OIO-WSDL | Guide til udvilkling og anvendelse af OIOWSDL, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/standarder-for-serviceorienteret-infrastruktur/standarder-for-webservices/filer-til-standarder-for-webservices/OIOWSDL_english.pdf |
OIO-NDR | OIO Namegivnings- og Designregler, OIO-NDR version 3.2, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/datastandardisering/oioxml-udvikling/regler/ndr-3.2 |
Data Model | MinSpærring Data Model - MinSpærring Data Model |
IDWS | OIO-IDWS 1.1 |
Læsevejledning
I dokumentet bruges begreberne autorisation og autoriseret primært i en sikkerhedskontekst, det vil sige i forståelsen af, at en person eller et system er autoriseret til at bruge en given ressource. Hvis begreberne anvendes på sundhedspersonale med dansk autorisation, der er anført i Sundhedsstyrelsens autorisationsregister, vil det blive udtrykkeligt angivet.
...
Det antages at læseren har general forståelse for SOAP-basterede Web Services. Derfor er tekniske termer som SOAP, WSDL osv. ikke beskrevet. Kendskab til Den Gode Webservice (DGWS) 1.0.1beskrevet i [DGWS 1.0] og [DGWS 1.0.1] vil gøre forståelsen nemmere.
Dokument historik
Version | Date | Responsible | Description |
0.1 | 24.2.2012 | Systematic | Initial version. |
0.9 | 14.5.2012 | Systematic | Clarification and elaboration of Web service semantics (section 4). Clarification of attributes for user identification and explicit consent scenario. Specification of consent registration for foreign health professionals. |
0.91 | 16.5.2012 | Systematic | Clarification of how organization identification is based on SOR-code has been added to section 2.3 and 2.4. Redundant information removed from section 3.2.2. Clarification of how organization identification is based on SOR only has been corrected in section 5.5. |
1.0 | 29.6.2012 | Systematic | The user system responsibilities has been updated, SOAP-faults added, schemas updated, general improvements. Section 7 concerning WSDL added. |
1.1 | 28.11.2014 | Systematic | References to National Patient Index (NPI) removed. |
1.2 | 09.09.2016 | Systematic | Changed nsi:skscode to nsi:skskode and nsi:sorcode to nsi:sor to fit XML schema |
1.3 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
22.10.2018 | KIT | Document moved from Word to Confluence. Original document name was: IFS0013 Consent Administration Service Interface Description.docx | |
14.05.2020 | KIT | SDS-3883 Etablering af IDWS snitflade | |
22.10.2020 | KIT | SDS-3875 A new version of the interface has been added. This interface matches the underlying validations. | |
17.11.2020 | KIT | Oversat til dansk |
Bruger og anvendersystems ansvar
For nogle af brugsscenarierne (og dermed webserviceoperationerne) beskrevet i dette dokument er det tilladt for en anden person end borgeren selv at udføre handlingen (kaldet at udføre handlingen på borgerens vegne). I dette tilfælde er det anvendersystemets ansvar at sikre, at borgeren har givet sit samtykke til, at personen kan udføre denne handling, før den udføres.
...
Det er muligt via servicen at oprette to (eller flere) registreringer, der er identiske set fra borgernes synspunkt. For eksempel ved SOR-koder, der mappes til den samme afdeling, ved overlappende datoer eller simpelthen helt identiske registreringer.
Servicen kontrollerer ikke, om der oprettes identiske registreringer, og det er følgelig anvendersystemets ansvar at sikre, at der ikke oprettes nye registreringer, der er identiske med allerede eksisterende.
MinSpærring Administration Anvenderscenarier
I det følgende afsnit beskrives de brugsscenarier, som MinSpærring Administration understøtter.
En ny version af snitfladen er tilføjet. I denne grænseflade er operationerne ConsentAdd og ConsentModify opdelt i to separate operationer - i alt fire operationer: ConsentAddPositiveV2, ConsentAddContraintV2, ConsentModifyPositiveV2, ConsentModifyConstraintV2
Sundhedsfaglig Registrerer på Vegne af en Borger
En sundhedsfaglig er i stand til at tilføje et samtykke eller en spærring på borgerens vegne til borgerens nuværende registreringer.
...
Dette brugsscenarie understøttes af operationen ConsentAddPositiveV2 eller ConsentAddConstraintV2 i den nye version af grænsefladen til administration afregistreringer.
Borger Henter en Oversigt Over Nuværende MinSpærring Registreringer
En borger kan hente et komplet overblik, over de registreringer der er for borgeren i MinSpærring, hvad enten de er registreret af borgeren, en person på vegne af borgeren eller af en sundhedsfaglig.
...
Resultatet af operationen er en komplet liste over alle aktive og inaktive registreringer for den pågældende borger.
Registrering af Spærring
En borger kan registrere en spærring, der dækker:
...
Dette brugsscenarie understøttes af operationen ConsentAddPositiveV2 i den nye version af grænsefladen til MinSpærring Administrtation.
Registrering af Samtykke
En borger kan registrere samtykke, der dækker:
...
Dette brugsscenarie understøttes af operationen ConsentAddConstraintV2 i den nye version af grænsefladen til MinSpærring Administration.
Borger Ændrer Registrering
En borger kan ændre en eller flere samtykker eller spærringer.
...
Dette brugsscenarie understøttes af operationerne ConsentModifyPositiveV2 eller ConsentModifyConstraintV2 i den nye version af grænsefladen til MinSpærring Administration.
Borger Ophæver Spærring/Samtykke
En borger kan ophæve samtykker og spærringer.
...
Dette brugsscenarie understøttes af operationen ConsentRevokeV2 i den nye version af grænsefladen til MinSpærring Administration.
MinSpærring Administration Web Service
Læsevejledning
Skabelonen nedenfor bruges til at dokumentere de operationer, der tilbydes i MinSpærring Administration. De vigtigste elementer til input og output er beskrevet i MinSpærring Administration WebService Skemaer.
Navn: <operation> | |
---|---|
Beskrivelse: | Beskriver operationens formål. |
Forespørgsel: | Parametre til input. |
Svar: | Parametre i svar. |
Fejlhåndtering: | Beskriver fejlhåndtering. Refererer typisk til den generelle beskrivelse af fejlhåndtering. |
Roller: | Beskriver krævede roller. |
Forudsætninger: | Beskriver forudsætninger der skal være opfyldt for at operationen kan udføres. |
Web Service - ConsentAdministration (Original)
Operation – ConsentRegistrationsGet
Navn: ConsentRegistrationsGet | |
---|---|
Beskrivelse: | Henter alle registreringer for en given borger. |
Forespørgsel: | ConsentRegistrationsGetRequest der består af: PatientPersonCivilRegistrationIdentifier Identifikation af borger der forespørges på. |
Svar: | ConsentRegistrationsGetResponse der består af: ConsentRegistrations Liste af alle aktive og inaktive registreringer for borgeren. |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Operation – ConsentAdd
Navn: ConsentAdd | |
---|---|
Beskrivelse: | Tilføjer en eller flere samtykker eller spærringer for en given borger. |
Forespørgsel: | ConsentAddRequest der består af: ConsentAdds liste af beskrivelser af registreringer af samtykker/spærringer, der skal tilføjes. Bemærk, at borgeren er identificeret i ConsentAdds. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, sundhedsfaglig, person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. Gentagne kald med identiske parametre vil der blive oprettet flere identiske spærringer eller samtykker. |
Operation – ConsentModify
Navn: ConsentModify | |
---|---|
Beskrivelse: | Opdaterer regsitreringer for en borger. |
Forespørgsel: | ConsentModifyRequest der består af: ConsentModifications Liste af beskrivelser af samtykker/spærringer, som ønskes modificeret. Bemærk, at borgeren er identificeret i ConsentModification. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, person på borgerens vegne |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Operation – ConsentRevoke
Navn: ConsentRevoke | |
---|---|
Beskrivelse: | Tilbagekalder en eller flere registreringer i MinSpærring. Dette finder sted ved inaktivering af givne registreringer. |
Forespørgsel: | PatientConsentRevokeRequest der består af: ConsentRevocations Liste af beskrivelser af registreringer, der skal tilbagekaldes. Bemærk, at borgeren er identificeret i ConsentRevocation. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Web Service - Consent_Administration (V2)
Operation – ConsentRegistrationsGetV2
Name: ConsentRegistrationsGet | |
---|---|
Beskrivelse: | Henter alle registreringer for en given borger. |
Forespørgsel: | ConsentRegistrationsGetRequest der består af: PatientPersonCivilRegistrationIdentifier Identifikation af borger der forespørges på. |
Svar: | ConsentRegistrationsGetResponse der består af: ConsentRegistrations Liste af alle aktive og inaktive registreringer for borgeren. |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Operation – ConsentAddPositiveV2
Name: ConsentAddPositiveV2 | |
---|---|
Beskrivelse: | Tilføjer et eller flere samtykker for den givne borger. |
Forespørgsel: | ConsentAddPositiveV2Request der består af: ConsentAdds Liste af samtykker, der skal tilføjes. Bemærk, at borgeren er identificeret i ConsentAdds. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, sundhedsfaglig, person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. Gentagne kald med identiske parametre vil der blive oprettet flere identiske spærringer eller samtykker. |
Operation – ConsentAddConstraintV2
Name: ConsentAddPositiveV2 | |
---|---|
Beskrivelse: | Tilføjer en eller flere spærringer for den givne borger. |
Forespørgsel: | ConsentAddConstraintV2Request der består af: ConsentAdds Liste af spærringer, der skal tilføjes. Bemærk, at borgeren er identificeret i ConsentAdds. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger, sundhedsfaglig, person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. Gentagne kald med identiske parametre vil der blive oprettet flere identiske spærringer eller samtykker. |
Operation – ConsentModifyPositiveV2
Name: ConsentModifyPositiveV2 | |
---|---|
Beskrivelse: | Modificerer et eller flere samtykker for en borger. |
Forespørgsel: | ConsentModifyPositiveV2Request der består af: ConsentModifications Liste af samtykker som ønskes rettet. Bemærk, at borgeren er identificeret i ConsentModification. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger eller person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Operation – ConsentModifyConstraintV2
Name: ConsentModifyConstraintV2 | |
---|---|
Beskrivelse: | Opdaterer en eller flere spærringer for en borger. |
Forespørgsel: | ConsentModifyConstraintV2Request der består af: ConsentModifications Liste af spærringer som ønskes rettet. Bemærk, at borgeren er identificeret i ConsentModification. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger eller person på vegne af borger. |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
Operation – ConsentRevokeV2
Name: ConsentRevoke | |
---|---|
Beskrivelse: | Tilbagekalder en eller flere registreringer i MinSpærring. Dette finder sted ved inaktivering af givne registreringer. |
Forespørgsel: | PatientConsentRevokeRequest der består af: ConsentRevocations Liste af registreringer der skal tilbagekaldes. |
Svar: | Ingen |
Fejlhåndtering: | Se den generelle beskrivelse af fejlhåndtering. |
Roller: | Borger |
Forudsætninger: | Både bruger og brugersystem skal godkendes som beskrevet i afsnitet Web Service Sikkerhed. |
MinSpærring Verifikation Web Service Semantiker
Besked format
Web servicen forventer SOAP beskeder. SOAP headeren indeholder sikkerheds header og Medcom header som krævet i DGWS 1.0.1. Udover dette skal der også være en HSUID header.
...
Formatet af sikkederhedsheader og Medcomheader er beskrevet i [DGWS 1.0] og [DGWS 1.0.1]. Formatet for HSUID-headeren er beskrevet i [HSUID-Header].
Attributter i HSUID headeren når bruger er borger
Når anvenderen af servicen er en borger så er det attributerne i tabel 1 der anvendes.
...
Tabel 1 Attributer i HSUID-header når bruger borger.
Attributter i HSUID headeren når bruger er sundhedsfaglig
Når brugere er en sundhedsfaglig person er det nedenstående attributter der skal være i HSUID headeren.
...
Bemærk at det er anvendersystemets ansvar at sikre konsistes mellem de angive organisationer.
Web Service Sikkerhed
Sikkerheden er baseret på SOSI-integrationsmønstret i Den Gode WebService (DGWS). Godkendelse sker via STS på NSP'en og er baseret på OCES digitale certifikater. Som udgangspunkt kræves der et medarbejdercertifikat (MOCES). Initielt kan visse systemer, i en overgangsperiode, anvende et VOCES certifikat.
Yderligere sikkerhedsaspekter, herunder autorisation, integritet, fortrolighed, tilgængelighed og fortrolighedshensyn, håndhæves kun i nogen grad af den tekniske service. De aspekter, der i øjeblikket ikke håndteres af den tekniske tjeneste, håndteres i serviceaftalen, som specificeret af den dataansvarlige myndighed (SDS) som forbrugere af tjenesten skal acceptere.
Godkendelse
Godkendelse af anvendersystemer
Når STS'en signatur af ID korter er valideret med succes har anvenderen adgang.
Udover dette skal anvendersystemet være whitelisted baseret på system delen af ID-kortet.
Godkendelse af bruger
Når anvendersytemet er godkendt bliver brugeren godkendt via HSUID header attributen nsi:ActingUserCivilRegistrationNumber.
...
Det er anvenders ansvar at sikre at personen må agere på vegne af borger.
Udløb af ID-kort
En request med et ID-kort der er mere end 24 timer gammelt i forhold til udstedelsestidspunkt afvises.
Status koder og flow status
Som krævet i DGWS 1.0.1 anvendes kun HTTP status kode 200 og 500.
Ved HTTP status kode 200 er FlowStatus altid flow_finalized_succesfully.
Timeout ved web-service operationer
Timeout er det samme som standard timeout på NSP platformen.
Session
Alle kald håndteres i sin egen session.
...
Dette afviger fra DGWS 1.0.1 i forhold til håndtering af genfremsendelse.
Tildeling og genbrug af flow-ID
Hvis request indeholder et flow-ID bliver det genbrugt i svaret. Håndtering af flow-ID sker i henhold til DGWS 1.0.1.
Behandling af anmodning om Non-Repudiation
Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in [DGWS 1.0].
Digital signering af svar understøttes ikke. På anmodning om Non-Repudiation returneres en fejlfejlmeddelelse som beskrevet i [DGWS 1.0].
Fejlhåndtering
SOAP fejl
SOAP-fejl returneres som beskrevet nedenfor. Der er valgt en struktur, hvor både standardfejlkoder som beskrevet i [DGWS 1.0] og servicespecifikke fejlkoder kan returneres.
...
Kodeliste 1 Struktur af SOAP-fejl returneret fra Web Service Operation. Eksemplet viser FaultCode, der bruges, når ID-kortet er udløbet.
SOAP Fault Status Koder
For alle web service operationer, der er beskrevet i afsnit 3, anvendes SOAP-fejl med FaultCode-værdier som anført i tabel 2, der stammer fra DGWS 1.0.1.
...
WSDL'en tilhørende servicen specificerer ikke SOAP fejlkoder for hver operation.
Web Service Input Validering
Nedenstående valideres:
- Korrekt formateret HSUID-header er inkluderet i SOAP-headeren, inklusive de attributter, der henholdsvis kan og skal være til stede for en given brugertype som beskrevet i afsnit 4.1.1. Desuden valideres det, at attributværdier hører til etablerede værdisæt og ikke er null eller simpelthen mellemrum
ID kort i security header er valid og signeret af STS'en og yderlige krav i sektion 4.2 er opfyldt.
- CPR numre er gyldige og findes i enten autorisationsregistret (for sundhedspersoner) eller stamdataregistret (for borgere).
- Organisations ID'er er valide. Valid betyder at det er en valid SOR, SHAK eller Yder nummer.
- At ValidFrom ikke ligger i fortiden. Bemærk at man som anvender godt kan angive 'nu' som ValidFrom, systemet tillader værdier der ligger en lille smule før serverens tid (som udgangspunkt 60 sekunder).
...
XML skema validering.
Validering af, at de angivne autorisationsnumre er gyldige og findes i autorisationsregisteret
Validering af, at der er konsistens mellem sundhedspersonens organisations-id'er, når der gives flere ID- og klassificeringssystemer.
Validering af, at en sundhedsperson er tilknyttet den angivne organisation
Validering af, at brugeren handler på vegne af den erklærede sundhedsperson
Standarder
MinSpærring Verifikation er baseret på nedenstående standarder. :
...
SOAP version 1.1
Soap Fault version 1.1
WS-I Basic Profile 1.1
OIO naming and design rules
DGWS 1.0.1, with the exception of requirements regarding retransmission and control of reuse of message ID as described in section 4.5.1, and with the exception of structure used on errors as described in section 4.7.
MinSpærring Administration WebService Skemaer
Dette afsnit giver en generel beskrivelse af nøgleelementerne i XML-skemaerne, der sammen med WSDL definerer de services der er beskrevet tidligere Hvor eksisterende OIO-typer identificeres, angives den i parentes efter elementnavnet. Derudover tilvejebringes kardinalitet, når et element ikke er obligatorisk.
ConsentItem
Element-navn | Beskrivelse |
CitizenCPR | borgerens CPR nummer. |
ConsentId | Unik ID på registreringen |
PositiveConsent | Sandt hvis der er tale om et samtykke. |
What[0..1] | Beskrivelse af hvilke data registreringen dækker. |
Who [0..1] | Beskrivelse afsundhedsfaglig person eller organisation som registreringen dækker. |
ValidFrom | Hvornår registreringen er gyldig. Bemærk at dette kun er en dato. |
ValidTo [0..1] | Hvornår registreringen ikke længere er gyldt. Bemærk at dette kun er en dato. |
WhatItem
Element-navn | Beskrivelse |
OrganizationIdentifier | Identifikation af specifik sundhedsorganisation, muligvis med underorganisationer, hvorfra data stammer |
IncludeSuborganizations | Om data fra underorganisationer for den angivne organisation også er inkluderet i registreringen. |
ReferralStartDate [0..1] | Startdato fra hvor data er gældende. |
ReferralEndDate [0..1] | Slutdato fra hvor data er gældende. |
WhoItem
Element-navn | Beskrivelse |
HealthcareProfessionalIdentifier | Identifikation af en bestemt sundhedsfaglig ved hjælp af CPR-nummer. |
Eller | |
OrganizationIdentifier | Identifikation af specifik sundhedsorganisation, muligvis inkluderende underorganisationer. |
Eller | |
ForeignHealthcareProfessionals | Angiver med værdien sandt, at samtykke dækker udenlandske sundhedspersonale (epSos). |
IncludeSuborganizations | Om data for underorganisationer for den angivne organisation også er inkluderet i registreringen. Kun relevant, hvis OrganizationIdentifier er udfyldt. |
ConsentAdds
Element-navn | Beskrivelse |
ConsentItems | Liste af ConsentItem. |
ConsentRegistrations
Element-navn | Beskrivelse |
ConsentRegistrations | Liste af ConsentItem. |
ConsentModification
Element-navn | Beskrivelse |
ConsentItems | Liste af ConsentItem |
ConsentRevocation
Element-navn | Beskrivelse |
ConsentRevocations | Liste af ConsentItem. |
Styring
Dokumentation
Til MinSpærring Administration er grænsefladen mellem anvendersystemerne og administration versioneret.
...
- den tekniske specifikation af skemaer og servicebeskrivelser (dokumenteret som en WSDL-fil, se afsnit 7)
dokumentation for den semantiske og funktionelle betydning af data, der udveksles (dokumenteret i dette dokument).
Versionering
Som en del af WSDL for ConsentAdministration er der headers der er definereret i andre standarder. Selve request til ConsentVerification følger nedenstående navngivning.
...
Bemærk dog at hvis der laves nye versioner af snitfladen skal versioneringen ske ved hjælp af en datoangivelse som det kan ses i nyeste version af MinSpærring Aministration snitfladen.
WSDL
WSDL til servicen kan tilgås ved at tilgå det endpoint servicen udstiller WSDL på. I test2 miljøet er det http://test2-cnsp.ekstern-test.nspop.dk:8080/consent-administration/service?wsdl. Hvis tjenesten på NSP miljøet ikke er tilgængeligt kan servicen startes op ved hjælp af de leverede docker-compose filer og WSDL kan tilgås der.
...