...

TODO: sikre at program flow og roller fremgår af "guide til anvendere" ellers inkluder

Brugertyper og adgangsscenarier

TODO: gælder nedenstående også for repository?

DDS Registry understøtter en række brugertype og adgangsscenarier. Disse brugertyper stille forskellige krav til autentifikations- og kaldkontekst. Derudover er anvendelsen af de eksterne services (samtykke, behandlingsrelation, minlog) forskellig for de forskellige adgangsscenarier.

Først gennemgåes de forskellige brugertyper og adgangsscenarier på et overordnet niveau (User Stories). Herefter beskrives, hvordan DDS Registry anvender eksterne services (samtykke, minlog og behandlerrelationservice) i forhold til de forskellige scenarier.

Endelig gennemgås adgangsscenarierne i forhold til den gældende sikkerhedsprotokol på DDS Registry: Den Gode Webservice (DGWS). Det gennemgåes, hvorledes adgangsscenarierne kan implementeres i autentifikations- og kaldkontekst for DGWS: Sosi Id-kort og HSUID header.

Brugertyper og adgangsscenarier

DDS Registry understøtter følgende DDS brugertyper:

• Borger: Borgere kan tilgå egne data, eller data på andre borgere, som de har en passende relation til (børn, fuldmagt)
• Sundhedsperson: Sundhedspersoner kan tilgå data på borgere, hvis der er hjemmel til dette (behandlingsrelation, ikke-negativt samtykke, værdispring)
• Ikke-autoriseret sundhedsprofessionel: Myndighedspersoner uden lægefaglig autorisation, men som har brug for at tilgå data på borgere (f.eks. adgang til aftaler for kommunale medarbejdere)

De forskellige DDS brugertyper giver anledning til en række adgangsscenarier dvs. måder, hvorpå disse kan tilgå DDS Registry for fremsøgning af dokumenter for et givent CPR nummer. 

Brug af eksterne services ved adgangsscenarier

De forskellige adgangsscenarier giver anledning til forskellige anvendelser af eksterne services. Disse anvendelser er opsummerert i nedenstående skema:

Adgangsscenarier og DGWS

Ovenstående adgangsscenarier bestemmes i DDS Registry ud fra bruger- og kaldkonteksten i DGWS - nemlig SOSI Id-kort og HSUID headeren. 

DDS Registry bestemmer DDS brugertypen udfra kaldkonteksten: Nærmere bestemt udfra HSUID-headerens attributter UserType samt ResponsibleUserAuthorizationCode. Disse kan antage een af følgende værdier brugertyper:

• nsi:Usertype == nsi:Citizen  → DDS Borger
• nsi:Usertype == nsi:HealthcareProfessional samt lovlig værdi i nsi:ResponsibleUserAuthorizationCode→ DDS Sundhedsperson
• nsi:Usertype == nsi:HealthcareProfessional samt ingen, tom eller '-' værdi i nsi:ResponsibleUserAuthorizationCode → DDS Ikke-autoriseret sundhedsperson
  
  

Hver brugertype kræver, at der i det indgående kald findes et gyldigt SOSI id-kort. I det nedenstående gennemgåes de forskellige krav til fremskaffelsen af SOSI-idkortet for de forskellige brugertyper.

Adgangsscenarier og tests

De ovenstående adgangsscenarier giver anledning til en række integrationstests.

Målene med integrationstestene er at udføre en række tests, der påviser at:

• Adgangsscenarierne er understøttet af DDS som beskrevet ovenfor: Dvs det er muligt at få data ud af DDS i de forskellige scenarier
• Negative tests: For hvert scenarie vil integrationstestene inkludere en række negative tests .. det tjekkes f.eks. at der ikke kan anvendes værdispring i scenarie IA-1

Integrationstestene er bygget op på følgende måde:

• Integrationstestene i DDS er delt ind i testklasser, der dækker de ovenstående scenarier. De er navngivet med scenariernes ID som prefix og en efterfølgende beskrivende tekst , så sammenhængen med dokumenationen bevares.
• Alle testcases i integrationstestene er implementeret som metoder, der har en titel, der forklarer intentionen med testen.
• Alle testcases er bygge op efter samme skabelon med kommentarer, der klart definerer præconditions (Given), aktivering af funktion (When) og tjek af svar/postconditions (Then). Se f.eks. Martin Fowler: Given-When-Then

Således indeholder integrationstestsuiten følgende:

• B1BorgerVocesIntegrationsTest
• B2BorgerPaaVegneAfVocesIntegrationsTest
• S1SundhedspersonMocesIntegrationTest
• S1SundhedspersonVocesIntegrationTest
• S3SundhedspersonPaaVegneAfMocesIntegrationsTest
• S3SundhedspersonPaaVegneAfVocesIntegrationsTest
• IA1IkkeAutoriseretBrugerLaegeSekretaerIntegrationsTest
• IA1IkkeAutoriseretBrugerSundhedsAssistentIntegrationsTest
• IA1IkkeAutoriseretBrugerUdenRollerIntegrationsTest

For afvikling af integrationstests henvises til dokumentet DDS - Testvejledning.

Fordeling af ansvar

Der er foretaget en fordeling i ansvar for gennemførelse af aktiviteter, der foregår ved udtræk. Ansvarsfordelingen er som følger:

• DDS Repository forestår alle aktiviteter undtagen kontrol af dokumentspecifikke samtykker
• Kildesystemer forestår fremfinding af dokumenter samt kontrol af dokumentspecifikke samtykker.

Rationalet bag denne fordeling er beskrevet i afsnit 'Kontrol af data-specifikke samtykker foretages af kildesystem' under designbeslutninger.

TODO: indsæt Registry i ovenstående liste

Behandling af udtræk i DDS Repository

I DDS guide til anvendere, afsnit hentning er der i detaljer redegjort for, hvordan DDS repository udtrækker dokumenter. Nedenfor er udvalgte områder af denne logik uddybet.

Repository bestemmelse af kildesystem(er)

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:

• repositoryUniqueId, en OID, der identificerer det kildesystem, hvorfra dokumentet kan udtrækkes
• documentUniqueId, en OID, der identificerer dokumentet
• homeCommunityId, en OID, der identificerer det Community, hvorfra dokumentet kan udtrækkes (bemærk, at der kun specificeres en værdi, når denne er anført i svaret fra en Registry Stored Query, fx i svaret fra et DDS Registry)

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:

• homeCommunityId bruges til at bestemme webservice endpoint for Responding Gateways (altså repositories)
• hvis homeCommunityId identificerer det lokale IHE-fællesskab, anvendes repositoryUniqueId til at bestemme webservice endpoint for repositories

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:

1. Hvis homeCommunityId er anført i et DocumentRequest-element i Retrieve Document Set-request’en, da foretages opslag i konfiguration på det homeCommunityId
2. Fremfindes et eller flere webservice-endpoints, da tilføjes disse til mængden af webservice-endpoints (dermed fortsættes til næste DocumentRequest-element)
3. Der foretages opslag på repositoryUniqueId i DDS Repositorys konfiguration
4. Fremfindes et webservice-endpoint, da tilføjes dette til mængden af webservice-endpoints (dermed fortsættes til næste DocumentRequest-element)
5. Fremfindes ingen webservice-endpoints, da tilføjes repositoryUniqueId’et til mængden over id, der ikke kunne fremfindes. Disse forespørgsler resulterer i en fejl hver i det resulterende svar.
6. De webservice-endpoints der ikke kan kontaktes, resulterer i en fejl i det resulterende svar.

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.

TODO: lav tegning til gliffy

Image Modified

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:

• Omkonfigureres til at kende den tilføjede dokumentkildes repositoryUniqueId og webservice endpoint, eller
• Omkonfigureres så Dokumentkilde B’s webservice endpoint kendes via dens homeCommunityId (og ikke dens repositoryUniqueId)

Forudsætningen for at mekanismen ikke falder tilbage til opslag på repositoryUniqueId, er at:

• homeCommunityId blev specificeret i metadata under registrering
• homeCommunityId blev returneret ved opslag (følger automatisk, hvis specificeret under registrering af metadata)
• homeCommunityId indgår i DDS Repositorys konfiguration (liste over kendte services)

Behandling af udtræk i kildesystem

Et kildesystem har følgende ansvar:

• Overholdelse af snitflade og adfærd for IHE XDS.b ITI-43
• Fremfindelse af dokument(er)
• Kontrol af data-specifikke samtykker (medmindre der er tale om værdispring)
• Frafiltrering af dokumenter/dokument-dele omfattet af data-specifikke samtykker (herunder indsættelse af advarsler i svaret ved frafiltrering grundet samtykker samt advarsel ved manglende evne til at kontrollere samtykker).

Designmålsætninger og -beslutninger

Designmålsætninger

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.

Tabel 1: Designmålsætninger og deres indbyrdes vigtighed

Designbeslutninger

I dette afsnit fastholdes væsentlige design beslutninger samt deres rationale. Hvis relevant, fastholdes også designs, som er afvist samt rationalet herfor.

Logning vha Log4j

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.

Logning af flowID

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.

Brug af NSPUtil til Service Level Agreement (SLA) logning

SLA-logning understøttes ved hjælp af (SLA) logningsfunktionaliteten i NSPUtil.

SLA-logningen logger all kald til DDS 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.

I DDS - Driftsvejledning er beskrevet en liste af XDS-fejl indlejret i svar fra XDS Registry/XDS Repository/XDS-infrastruktur, der giver anledning til SLA-logning som fejlet, udadgående kald, på trods af at kaldet til den eksterne XDS-komponent (Registry/Repository eller infrastruktur) er succesfuldt. Mens fejlen XDSMissingHomeCommunityId fortrinsvis kan bero på fejl fra dokumentanvenders side, så er den inkluderet fordi den også kan skyldes fejlkonfiguration i XDS-infrastrukturen. De øvrige fejl i listen er udtryk for server-side fejl eller fejl i XDS-infrastruktur. Fejlene, hvoraf nogle reflekterer situationer, der kan opstå transient i XDS-infrastrukturen, skal håndteres af dokumentanvendere, da de kan betyde, at ikke alle tilgængelige oplysninger returneres i svar.

Selvom fejlene ikke er udtryk for, at DDS ikke fungerer korrekt, så SLA-logges de af DDS som fejlet for at lette detektion og fejludbedring.

Auditlogning

Auditlogning i DDS Registry sker vha AuditAPI'et (introduceret i Image AddedSDS-2506 - Auditlogging af DDS via AuditAPI ARKIVERET ).

ITI-18: foretag auditlogning af patient-id, bruger-id, på-vegne-af-id og for hver DocumentEntry (DE) i returneret svar (der kan være frafiltreret metadata pga. samtykker): DE.uniqueId, DE.repositoryUniqueId, DE.homeCommunityId, DE.typeCode.

ITI-43: foretag auditlogning af patient-id, bruger-id, på-vegne-af-id og for hver DocumentResponse (DR) i returneret svar (der kan være frafiltreret metadata pga. samtykker): DR.uniqueId, DR.repositoryUniqueId, DR.homeCommunityId.

Statisk konfiguration i propertyfil

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 - Driftsvejledning.

Applikationskonfiguration konfigureres i filerne DDSRegistry.properties og 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 Registry’s og Repositories 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:

• Generel DDS Registry/Repository fejl- og debug-logning. Den generelle logning konfigureres ved at angive en log4j-logger property med navn log4j.logger.dk.nsi.
• Værdispringsloggen konfigureres med en log4j-logger property med navn log4j.logger.consentoverride.
• Performanceloggen, der kan bruges til logning umiddelbart før og efter kald til andre services, konfigureres med en log4j-logger property med navn log4j.logger.performancelogger.

Dynamisk konfiguration i database

DDS skal have adgang til en datasource ved navn ’WhitelistDS’ for at kunne lave autorisation af anvendersystemer vha. whitelist.

Brug af datasources

DDS Registry skal have adgang til:

• en datasource med navn ’SORDS’, der har adgang til SOR-databasen til brug ved kald af behandlingsrelationsservicen
• en datasource med navn ’AuthDS’, der har adgang til autreg-databasen. Dette benyttes ved kontrol af autorisationskode
• en datasource med navn ’WhitelistDS’, der har adgang til whitelist databasen til brug ved autorisation af anvendersystemer

Implicitte headers i WSDL

For at DDS Registry 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 Registry WSDL, men ikke input/output-beskederne.

Kaldsemantik i header

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.

Advarsler i svaret

For entydigt at kunne kommunikere, at samtykkebegrænsninger har bevirket fravær af metadata i svaret fra opslag på 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 [IHE vol. 3], være anvendt på bekostning af entydighed for så vidt angår årsagen til fejlen/advarslen.

I afsnit 4.1.13 i [IHE vol. 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 Registry query snitflade] for de konkrete anvendelser af implementationsspecifikke fejl/advarsler.

Beslutning vedrørende servicearkitektur

Da DDS Registry ikke har behov for transaktionsstyring er den implementeret som almindelig web service og ikke som Java EE bean.

Asynkron involvering af kontrolservices

Kald til Samtykkeservice, MinLog og Behandlingsrelationsservice udføres i parallel, hvert kald som synkront kald.

Anvendelse af thread local request context

Invokere i DDS Registry for kald af MinLog, BRS, Samtykkeverifikationsservicen samt for XDS Registry benytter JAXWS klient-proxier.

Disse er tunge at skabe, da det involverer udstrakt grad af reflection. Dette er undgået ved at skabe klient-proxyerne en gang og genbruge dem ved hver forespørgsel.

En forudsætning for denne fremgangsmåde (når udstrakt brug af synchronized fravælges grundet ineffektivitet) er brug af trådsikker port.

Ifølge JAXWS specifikationen er klient-proxy porte ikke trådsikre.

Derfor anvendes en udvidelse i Apache CXF, der indgår i den underliggende platform i Wildfly, der sikrer trådsikker request context beskrevet i http://cxf.apache.org/faq.html#FAQ-AreJAX-WSclientproxiesthreadsafe?

Registry er i sine invokere afhængig af trådsikker request context stillet til rådighed af CXF-implementationen af JAXWS i Wildfly

Der er risiko for sammenblanding af patient-data/behandling af patient-data, hvis ikke CXF’s JAXWS-implementation anvendes.

Anvendelse af security API til validering af sikkerhedsbilletter

Valideringen af de indkommende sikkerhedsbilletter (OIO IDWS, SOSI Idkort) foretages udenfor selve komponenten vha det i security API.

Det er fortsat DDS egen opgave at validere, at den kaldende brugers kald er lovlige/giver mening og overholder de i DDS gældende forretningsregler.

Arkitekturdesign

Integration og test