DDS Repository tilbyder en snitflade til udtræk af dokumenter. Baseret på opslag på patienter i Dokumentdelingsservice Registry kan et anvendersystem benytte snitfladen for DDS Repository til at udtrække dokumenter.
Formålet med dette dokument er at beskrive systemarkitekturen for DDS Repository. For et overblik over systemet henvises til afsnit 4.1.
Nærværende dokument er tiltænkt udviklere og IT-arkitekter med interesse i anvendelsen af DDS Repository. Herunder hører naturligvis personer involveret i konkrete dokument-kildesystemers brug af DDS Repository.
I dokumentet bruges begreberne autorisation og autoriseret primært i en sikkerhedskontekst, dvs. i forståelsen at en person eller et system har tilladelse til at anvende en given ressource. Anvendes begreberne om sundhedspersoner med dansk autorisation opført i Sundhedsstyrelsens autorisationsregister vil dette fremgå eksplicit.
Version | Dato | Ansvarlig | Beskrivelse |
1.0 | 1.3.2013 | Systematic | Initiel udgave |
1.0a | 18.4.2013 | Systematic | Udgave til release candidate 1 |
1.1 | 19.6.2013 | Systematic | Kvalitetssikring |
1.2 | 28.11.2014 | Systematic | Nationalt Patientindeks (NPI) erstattet med Dokumentdelingsservice (DDS) |
1.3 | 05.05.2015 | Systematic | Kodereferencer er opdaterede pga. navneskifte fra NPI til DDS |
Formålet med denne sektion er at give et overblik over definitioner og dokumenter, der benyttes i dette dokument.
Definition | Beskrivelse |
DDS | Dokumentdelingsservice |
IHE | Integrating the Healthcare Enterprise |
IHE-fællesskab | Community i IHE XDS |
MTOM | Message Transmission Optimization Mechanism |
NSI | National Sundheds-IT |
NSP | Den Nationale Service Platform (inden for sundheds-IT) |
STS | Security Token Service |
XDS | Cross-Enterprise Document Sharing |
Alias | Beskrivelse |
Behandlingsrelationsservice ws | Behandlingsrelations- og Opfølgningsservice, Guide til Anvendere |
ConsentVerificationService ws | Samtykkeverifikation Service snitfladebeskrivelse (SSE/11734/IFS/0005) |
DGWS 1.0.1 | Den Gode Webservice 1.0.1, Medcom |
HSUID-header | Healthcare Service User Identification Header (SSE/11734/IFS/0006) |
ITI TF-2a | IHE IT Infrastructure Technical Framework – Volume 2a (ITI TF-2a) Transactions Part A – Sections 3.1 – 3.28, Revision 8.0 – Final Text, August 19, 2011, http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Rev8-0_Vol2a_FT_2011-08-19.pdf |
ITI TF-2b | IHE IT Infrastructure Technical Framework – Volume 2b (ITI TF-2b) Transactions Part B – Sections 3.29 – 3.51, Revision 8.0 – Final Text, August 19, 2011, http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Rev8-0_Vol2b_FT_2011-08-19.pdf |
ITI TF-3 | IT Infrastructure Technical Framework – Volume 3 (ITI TF-3) Cross Transaction Specifications and Content Specifications, Revision 8.0 – Final Text, August 19, 2011, http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Rev8-0_Vol3_FT_2011-08-19.pdf |
IHE Document Repository WSDL | WSDL for XDS.b Document Repository, ftp://ftp.ihe.net/TF_Implementation_Material/ITI/wsdl/XDS.b_DocumentRepository.wsdl |
ITI-43++ SOAP 1.1 WSDL | WSDL for RetrieveDocumentSet (ITI-43) med SOAP 1.1-binding udvidet med HSUID-header og DGWS-header |
ITI-43++ SOAP 1.2 WSDL | WSDL for RetrieveDocumentSet (ITI-43) med SOAP 1.2-binding udvidet med HSUID-header og DGWS-header |
MinLogService ws | Min-log Service snitfladebeskrivelse (SSE/11734/IFS/0003) |
MTOM SOAP 1.1 | SOAP 1.1 Binding for MTOM 1.0, (W3C Member Submission 05 April 2006) |
MTOM SOAP 1.2 | SOAP Message Transmission Optimization Mechanism, (W3C Recommendation 25 January 2005) |
DDS Repository drift | DDS Repository, Driftsvejledning (SSE/11734/OHB/0011) |
DDS Repository udvikling | DDS Repository, Guide til Udviklere (SSE/11734/PHB/0021) |
DDS Repository snitflade | DDS Repository snitfladebeskrivelse (SSE/11734/IFS/0009) |
Der etableres med løsningen en DDS Repository web service, som giver mulighed for både sundhedspersoner og borgere at udtrække dokumenter på baggrund af metadata registreret i dokumentdelingsservice.
DDS Repository benyttes som intelligent proxy for en eller flere dokumentkilder.
Udtræk gennemføres med operationen Retrieve Document Set, der er IHE XDS.b’s operation til udtræk af dokumenter fra et IHE repository.
Ved kald af webservice-operationen Retrieve Document Set på DDS Repository gennemføres følgende:
DDS Repository:
DDS Repository anvender eksterne ressourcer som vist i Figur 1 til at foretage behandling af et udtræk. Denne behandling er beskrevet i det følgende afsnit.
Figur 1 Anvendelse af services og databaser fra DDS Repository
Der er foretaget en fordeling i ansvar for gennemførelse af de aktiviteter beskrevet oven for, der foregår ved udtræk. Ansvarsfordelingen er som følger:
Rationalet bag denne fordeling er beskrevet i afsnit 3.2.1.
Hvad enten bruger af DDS Repository er borger eller sundhedsperson foretages først autentificering og autorisering af henholdsvis anvendersystem og bruger. Autorisation af anvendersystemet sker mod en whitelist i databasen.
Er bruger en borger viderestilles udtræk direkte til IHE Repository, og resultatet derfra returneres til anvendersystemet.
Er bruger en sundhedsperson sker følgende:
Udtræk sker ved anvendelse af operationen Retrieve Document Set, hvor der i request-beskeden indgår et eller flere DocumentRequest-elementer, hver med følgende indhold:
Som beskrevet i [ITI TF-2a] afsnit 3.18.4.1.2.3.8 anvendes homeCommunityId til at bestemme webservice-endpoint for services, der giver adgang til data inden for et IHE-fællesskab.
I [ITI TF-2b] afsnit 3.43.4.1.3 er det beskrevet, hvordan en XCA Initiating Gateway skal reagere på en Retrieve Document Set-request:
Denne adfærd ligger til grund for bestemmelsen af kildesystemer i DDS Repository beskrevet i det følgende.
Ved gennemløb af alle DocumentRequest-elementer i Retrieve Document Set-request’en skabes en mængde (Set) af webservice-endpoints og en mængde af id, der ikke kunne fremfindes:
Denne mekanisme (i DDS Repositorys bestemmelse af kildesystemer) er helt ortogonal på hvorvidt kildesystemer anvender XCA. Fordelen er, at DDS Repository ikke skal kende alle repositoryUniqueId (transitivt), således at et kildesystem i et IHE-fællesskab kan skifte til og fra XCA uden at DDS Repository-konfigurationen skal ændres.
Som vist i Figur 2 kan yderligere kildesystemer via XCA knyttes til et IHE-fællesskab uden ændring i konfigurationen i DDS Repository, når homeCommunityId er kendt af DDS Repository.
Figur 2 Konfiguration af DDS Repository baseret på repositoryUniqueId og homeCommunityId tillader tilføjelse af nye dokumentkilder. Når DDS Repository kender til dokumentkilde C’s webservice endpoint gennem dens homeCommunityId (IHE-fællesskab XYZ), da kan der tilføjes en ny dokumentkilde, her Dokumentkilde F, til IHE-fællesskabet via XCA uden at DDS Repository skal omkonfigureres.
I Figur 2 er Dokumentkilde B kendt direkte ved dens repositoryUniqueId. Tilføjes endnu en dokumentkilde via XCA til Dokumentkilde B, da skal DDS Repository enten:
Forudsætningen for at mekanismen ikke falder tilbage til opslag på repositoryUniqueId, er at:
Et kildesystem har følgende ansvar:
Systemet skal designes i overensstemmelse med de målsætninger og prioriteter, som er angivet i Tabel 1. Prioriteten af hver enkelt målsætning er angivet med 1 til 5 hvor 5 indikerer højest prioritet.
Mål | Prioritet | Bemærkning |
Correctness | 5 | Den overordnede funktionalitet omhandler patientsikkerhed og er reguleret af et omfattende lovgrundlag. |
Reliability | 4 | Prioriteret af hensyn til patientsikkerhed. |
Usability | 1 | Ingen brugergrænseflade. |
Security | 4 | Prioriteret for at opfylde lovkrav om beskyttelse af personhenførbare oplysninger. |
Performance | 3 | De specifikke performancekrav er ikke kendte, men performance har været prioriteret. |
Maintainability | 3 | Dokumentationskrav vedrørende arkitektur, vejledninger og API-dokumentation. |
Flexibility | 2 | Løsningen består af web services. Det giver den nødvendige fleksibilitet i det overordnede system. De enkelte services behøver ikke være fleksible. |
Testability | 3 | Løsningen skal være testbar via automatiske tests, da der ingen brugergrænseflade er. |
Portability | 1 | De grundlæggende teknologivalg er foretaget. Der bør som udgangspunkt ikke laves bindinger specifikt til JBoss. |
Reusability | 1 | Der er ingen forventning om genbrugelighed af DDS Repository business-logikken og filtrering, da disse formodentlig kun vil finde anvendelse i DDS Repository. |
Interoperability | 1 | Gennem webservice-snitflader opnås den ønskede interoperabilitet. |
Tabel 1: Designmålsætninger og deres indbyrdes vigtighed
I dette afsnit fastholdes væsentlige design beslutninger samt deres rationale. Hvis relevant, fastholdes også designs, som er afvist samt rationalet herfor.
Alternativer:
Når data-specifikke samtykker skal kontrolleres ved kald af Samtykkeverifikationsservicen skal sundhedspersonens organisation gives ved dennes kode i SOR-klassifikationen.
Ved kald af DDS Repository er der som beskrevet i [DDS Repository snitflade] mulighed for i HSUID-header at angive sundhedspersonens organisation ved:
Er SOR-koden ikke givet ved kaldet af DDS Repository, foretages mapning til SOR-kode ud fra organisation angivet HSUID-headeren. Den fremfundne SOR-kode tilføjes til HSUID-header brugt ved kaldet til kildesystemet, således at kildesystemet ikke skal foretage mapningen.
Snitfladen for DDS Repository skal indeholde SOAP-headere fra DGWS 1.0.1 og SOAP-header samt SOAP-body med indhold specificeret af IHE XDS.
DGWS 1.0.1 specificerer anvendelse af SOAP 1.1, mens webservices for IHE XDS er baseret på SOAP 1.2.
Det er valgt, at DDS Repository skal udstille services med SOAP 1.1-binding af hensyn til overholdelse af DGWS.
Konsekvensen af valget er, at MTOM-anvendelse sker med SOAP 1.1-binding [MTOM SOAP 1.1] og ikke [MTOM SOAP 1.2].
Både DDS Repository og kildesystemet har behov for at kende identifikation af den borger, der udtrækkes dokumenter om (patient-id). DDS Repository har behovet i kraft af, at denne skal kalde Samtykkeverifikationsservicen, Behandlingsrelationsservicen og MinLogRegistreringsservicen, hvor patient-id er krævet information. Tilsvarende skal kildesystemet kende patient-id, når data-specifikke samtykker kontrolleres ved kald af Samtykkeverifikationsservicen.
Patient-id indgår ikke i den request-struktur, der anvendes ved ITI-43 RetrieveDocumentSet.
Det er valgt, at tilføje en attribut til et enkelt patient-id til HSUID-headeren. Det er dermed anvendersystemets ansvar at specificere det korrekte patient-id. Med RetrieveDocumentSet er det muligt at udtrække dokumenter for flere dokument-id. Support blot for et enkelt patient-id har den konsekvens, at kald af RetrieveDocumentSet kun må anvendes, når alle specificerede dokument-id gælder samme patient. Det påhviler anvendersystemet at sikre, at dette er tilfældet.
Alternative løsninger:
Supplerende løsninger til valgte løsning:
Med RetrieveDocumentSet er det muligt at udtrække dokumenter for flere dokument-id. Som beskrevet i afsnit 3.2.3 angives et enkelt patient-id i HSUID-headeren.
Det er valgt, at der ikke foretages kontrol af overensstemmelse mellem patient-id angivet i HSUID-header og patient-id for de dokumenter, der ønskes udtræk af.
Det påhviler anvendersystemet at sikre, at der er overensstemmelse mellem angivne patient-id og patient-id for de dokumenter, der ønskes udtræk af.
Med RetrieveDocumentSet er det teknisk muligt med et kald at udtrække dokumenter for flere forskellige patienter. Af hensyn til patient-sikkerhed må der dog kun udtrækkes dokumenter for samme patient.
Det er valgt, at der ikke foretages kontrol af, at alle dokumenter, der ønskes udtræk af, vedrører samme patient.
Det påhviler anvendersystemet at sikre, at der kun forespørges om udtræk for samme patient.
Fejl- og debug-logning implementeres vha. log4j der konfigureres for hver enkelt service. Der oprettes som udgangspunkt en logfil pr. service.
I denne logges exceptions og stacktraces for evt. fejl, der kastes.
Hvis konfigurationen sættes til ’debug’-niveau, logges flowID fra SOAP-beskeders Medcom-header ved entry/exit af webservicemetoderne.
Logningen af flowID er implementeret for at muliggøre, i tilfælde af fejlsøgning, at man kan følge de kald, der har indgået i et forløb.
SLA-logning understøttes ved hjælp af (SLA) logningsfunktionaliteten i NSPUtil.
SLA-logningen logger all kald til DDS Repository og består bl.a. af: Tidspunkt for kald, navn på den kaldte metode, tidsmæssig længde på kaldet, id (MessageID) på den besked der behandles.
Audit logning foregår også gennem log4j, til kategorien ”audit”. Auditlogning skal logge
Typen af anvendelse er metodekaldet.
Servicekonfigurationen foretages i en properties-fil, der skal deployes på webserveren et sted i applikationens classpath.
Ændringer i konfigurationen skal ledsages af genstart af servicen, da konfigurationen indlæses og verificeres ved opstart af de enkelte services. Properties kontrolleres for tilstedeværelse i property-filen, ikke for anførte værdi.
For en beskrivelse af hvad der skal opsættes i konfigurationen, se [DDS Repository drift].
Applikationskonfiguration konfigureres i filen DDSRepository.properties. Al konfiguration af sikkerhed og klientopsætning angives i denne fil. Derudover angives også placeringen af logkonfigurationsfilen.
Serviceklientkonfiguration, der omfatter konfiguration af DDS Repositorys kald til andre services, udpeges i applikationskonfigurationen. Det er muligt at lade applikationskonfigurationen ”pege på sig selv” angive serviceklientkonfigurationsparametre i applikationskonfigurationen, men der kan også foretages serviceklientkonfiguration i separate filer.
Placeringen af serviceklientkonfiguration angives i applikationskonfigurationen.
Logkonfiguration udpeges i applikationskonfigurationen. I logkonfigurationsfilen angives logger-properties for:
DDS Repository skal have adgang til en datasource ved navn ’WhitelistDS’ for at kunne lave autorisation af anvendersystemer vha. whitelist.
DDS Repository skal have adgang til:
For at DDS Repository kan eksponere et webservice-interface, der i videst muligt omfang implementerer Registry Stored Query i henhold til IHE-standarden, er det søgt at minimere ændringer. Derfor er DGWS-headerne og HSUID-headeren tilføjet som implicitte headere, dvs. tilføjet til bindings i DDS Repository WSDL, men ikke input/output-beskederne.
Et generelt håndhævet princip for webservices er, at argumenter af betydning for semantikken i webservice-operationer skal være placeret i SOAP body og ikke i SOAP header.
Hensynet til overholdelse af IHE-standarden vejer dog tungere, hvorfor en parameter som angivelse af værdispring er fastholdt i HSUID-headeren, til trods for at parameteren har betydning for semantikken. Derved er SOAP body fastholdt som defineret af IHE-standarden.
For entydigt at kunne kommunikere, at samtykkebegrænsninger har bevirket fravær af metadata i svaret fra DDS Registry, er det valgt at benytte IHE-standardens mulighed for implementationsspecifikke fejlbeskrivelser. Alternativt skulle et af IHE-standardens fejlkoder, som beskrevet i afsnit 4.1.13 i [ITI TF-3], være anvendt på bekostning af entydighed for så vidt angår årsagen til fejlen/advarslen.
I afsnit 4.1.13 i [ITI TF-3] er beskrevet, hvordan implementationsspecifikke fejl/advarsler kan angives, herunder at errorCode skal sættes til "XDSRegistryError", mens codeContext skal indeholde detaljer om fejlsituationen.
Se [DDS Repository snitflade] for de konkrete anvendelser af implementationsspecifikke fejl/advarsler.
Da DDS Repository ikke har behov for transaktionsstyring er den implementeret som almindelig web service og ikke som Java EE bean.
Dette afsnit beskriver statiske såvel som dynamiske aspekter af systemarkitekturen, herunder baggrunden for de enkelte designvalg.
Den generelle servicestruktur er at servicen implementeres som en webservice, der implementerer det webinterface, der er genereret fra DDS Repository WSDL [ITI-43++ SOAP 1.1 WSDL]. Webservicen er en tynd skal, der for sin eneste weboperation (til udtræk) blot kalder den faktiske implementation DDSRepository.
Figur 3 Implementationen af webservice-interfacet
DDSRepository forestår autentifikation og autorisation af anvendersystem vha. DGWSProvider.
Som forberedelse til autentifikation og autorisation af bruger af webservicen foretager DDSRepository parsning og validering af SOAP-headerens HSUID-header vha. ValidatedHsuidAttributes. Autentifikation og autorisation af bruger varetages af UserCheck, der som input tager den skabte instans af ValidatedHsuidAttributes. Er brugeren en sundhedsperson og er der anført ansvarlig sundhedsperson cpr- og autorisationsnummer (fra Sundhedsstyrelsen), foretager UserCheck desuden kontrol af sammenhængen mellem cpr- og autorisationsnummeret.
Til behandling af udtræk kaldes DDSRetrieveDocumentLogic, som beskrevet i afsnit 4.2.
DDSRepository foretager fejlhåndtering ved at omdanne exceptions til SOAP fault med indhold som beskrevet i [DDS Repository snitflade]. En undtagelse herfra er dog ved exception pga. negativt samtykke mod en sundhedsperson, hvor der dannes en advarsel i et tomt svar, også beskrevet i [DDS Repository snitflade].
DDSRepository implementerer den sekvens af kald af services og håndtering af fejlsituationer, der er beskrevet i afsnit 2.1.1. Dog håndteres autentificering og autorisation af DDSRepository som beskrevet ovenfor.
Figur 4 DDSRetrieveDocumentLogic får dependency injected et antal delegates, der varetager kald til de forskellige services.
DDSRepository forestår orkestrering af kald til de forskellige services, hvor kaldene er pakket ind i ”invokere”:
I Figur 5 er vist et sekvensdiagram for DDSRepository.
Figur 5 Sekvensdiagram for DDSRetrieveDocumentLogic
Fælles for de service-invokere, der er beskrevet i afsnit 4.2 er at de hver især har ansvar for:
For ConsentVerificationServiceInvoker, MinLogRegistrationInvoker og TreatmentRelationInvoker anvendes serviceklienter, der arver fra SosiService. Derved får de ved instantiering automatisk en DGWSConsumer-instans og altså også cached ID-kort-håndtering. Når der laves kald af disse services bliver et ID-kort, der stadig er gyldigt, genbrugt fra tidligere kald, og om nødvendigt bliver nyt ID-kort indhentet automatisk fra STS.
Ved de tre invokere’s kald af operationer på hhv. samtykkeverifikationsservicen, MinLogRegistration-servicen og behandlingsrelationsservicen benyttes DGWSConsumer til at skabe de nødvendige DGWS-headere (Medcom- og sikkerhedsheader).
Ved kald til hhv. samtykkeverifikationsservicen og MinLogRegistration-servicen, der begge i tilgift forventer en HSUID-header, genbruges HSUID-headeren modtaget med kaldet af DDS Repository.
DocumentRetrieveInvoker er speciel derved, at kildesystemers ITI-43 snitflade ikke overholder DGWS og derfor ikke kræver ID-kort indhentet fra STS for at kunne kaldes.
Figur 6 Karakteristika for snitflader
ConsentOverrideLoggingInvoker foretager blot logning lokalt og kalder ikke nogen service.
SLA loggeren sørger for at foretage SLA logning af alle servicekald.
SLA loggeren er implementeret som et servlet filter defineret i webapplikationens web.xml-fil.
Der er ikke nogen specifik rækkefølge hvori DDS Repository og de services, den kalder, skal integreres.
I kraft af dens fejlhåndtering kan udtræk gennemføres når blot datasources, et kildesystems ITI-43-snitflade og samtykkeverifikationsservicen er tilgængelige.
For succesfuld gennemførelse af integrationstests skal alle services, DDS Repository er afhængig af dog være tilgængelige.
For en beskrivelse af byggeprocessen og eksterne/interne afhængigheder for servicen, se [DDS Repository udvikling].
Der findes følgende integrationstestklasse til DDS Repository: DDSRepositoryIT.
DDSRepositoryIT verificerer, at DDS Repository:
Der findes en række unittests, der sikrer at de forskellige del-komponenter er implementeret korrekt. Fx verificeres med DDSRetrieveDocumentLogicTest at services anvendes og at fejl håndteres som forventet i forskellige situationer.