Indhold
1 Introduktion
1.1 Formål
1.2 Læsevejledning
1.3 Dokumenthistorik
1.4 Definitioner og referencer
2 Introduktion til dokumentdeling af laboratoriesvars-dokumenter
2.1 Deployment af Svareksponeringsservice XDS-adaptere
2.2 Implementation af Svareksponeringsservice XDS-adaptere
3 Arkitekturbeslutninger
3.1 Svareksponeringsservice XDS Registry Adapter
3.2 Svareksponeringsservice XDS Repository Adapter
4 Håndtering af søgeparametre ved opslag på metadata
5 Design af Svareksponeringsservice XDS-adaptere
5.1 Svareksponeringsservice XDS Registry Adapter
5.2 Svareksponeringsservice XDS Repository Adapter
5.2.1 Håndtering af datoer
6 Svareksponeringsservice
Introduktion
Laboratoriesvarsdokumenter (svar fra laboratorier inden for specialerne mikrobiologi, klinisk biokemi og patologi) gøres tilgængelige gennem Dokumentdelingsservices (DDS) på den Nationale Service Platform (NSP). Derved underkastes opslag og indhentning af laboratoriesvarsdokumenter for den adgangskontrol, kontrol for behandlingsrelation og samtykkebeskyttelse samt logning i MinLog, som gennemføres af DDS.
DDS indhenter dokumentmetadata og laboratoriesvar ved at kalde Svareksponeringsservice XDS Registry Adapter og Svareksponeringsservice XDS Repository Adapter, samlet kendt som Svareksponeringsservice XDS-adaptere. Indholdet i dokumenter skaber Svareksponeringsservice XDS Repository Adapter ved at kalde Svareksponeringsservicen (SES) hos Laboratoriedatabanken.
Formål
Formålet med nærværende arkitekturbeskrivelse er at give en overordnet beskrivelse af den funktion, som Svareksponeringsservice XDS-adaptere leverer.
Læsevejledning
Det er tilstræbt, at der med læsning af afsnit 2 kan opnås en forståelse af Svareksponeringsservice XDS-adaptere, der letter opsætning, drift og til dels testning af denne.
Dokumenthistorik
Version | Dato | Ansvarlig | Beskrivelse |
|---|---|---|---|
1.0 | 18.08.2016 | Systematic | Initiel udgave |
Definitioner og referencer
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 |
NSI | National Sundheds-IT |
NSP | Den Nationale Service Platform (inden for sundheds-IT) |
PIH | Privacy Information Header |
PIW | Privacy Information Wrapper |
XDS | Cross-Enterprise Document Sharing |
SES | Svareksponeringsservice |
Alias | Beskrivelse |
|---|---|
Driftsvejledningen | Driftsvejledningen for Svareksponeringsservice XDS-adaptere, (SSE/11734/OHB/0017) |
PIH-spec | Kommende dokument |
PIW-spec | Kommende dokument |
SES snitflade | SvarEksponeringsService ServiceKontrakt v.1.04.pdf |
Deling af dokumenter sker gennem følgende aktører:
- Dokumentkilde er en aktør, der registrerer metadata om sine dokumenter i indeks og gør dem tilgængelige til senere indhentning
- Dokumentdelingsservice er et adgangspunkt for opslag i indeks, indhentning af dokumenter, samt registrering af metadata om dokumenter.
- Indeks er en aktør, hvor metadata om dokumenter er lagret.
- Dokumentanvender er en aktør, der i en forretningsmæssig kontekst skaber adgang for en bruger til opslag på metadata og indhentning af dokumenter.
Introduktion til dokumentdeling af laboratoriesvars-dokumenter
Formålet med SES XDS-adaptere er at kunne udstille patients laboratoriesvar i en dokumentdelingsarkitektur baseret på standarden IHE XDS.b. På den nationale serviceplatform (NSP) understøttes denne standard af Dokumentdelingsservicen, der i tilgift ved anvendelse af andre services på NSP'en foretager samtykkekontrol, igangsættelse af kontrol af behandlingsrelation samt logning.
Når en dokumentanvender laver opslag på en patient på DDS returneres metadata registreret om tilgængelige dokumenter vedrørende patienten. Disse metadata kan være registreret i det indeks, der er tilknyttet DDS, eller i andre indeks.
Figur 1 Svareksponeringsservice XDS Registry Adapter fungerer som indeks over laboratoriesvarsdokumenter-dokumentmetadata.
I dokumentdeling af laboratoriesvarsdokumenter er det komponenten Svareksponeringsservice XDS Registry Adapter, der fungerer som et indeks og returnerer metadata. Lidt atypisk gennemfører adapteren dette uden persisteret lager og uden at konsultere anden service. Den returnerer et standardsvar, hvor metadata er tilpasset til patienten.
Når en dokumentanvender vha. returnerede metadata har afgjort hvilke dokumenter, der ønskes indhentet, foretages indhentning af et eller flere dokumenter gennem DDS.
Figur 2 Svareksponeringsservice XDS Repository Adapter fungerer som dokumentkilde. Denne kalder Svareksponeringsservicen hos Laboratoriedatabanken.
I dokumentdeling af laboratoriesvarsdokumenter varetages rollen som dokumentkilde af komponenten Svareksponeringsservice XDS Repository Adapter. Når der indhentes dokument vha. metadata returneret fra Svareksponeringsservice XDS Registry Adapter, da henter DDS'en dokumentet fra Svareksponeringsservice XDS Repository Adapter. Dette er forudsat, at DDS er konfigureret til at kende Svareksponeringsservice XDS Registry Adapter som indeks og Svareksponeringsservice XDS Repository Adapter som dokumentkilde.
Når et identificeret dokument indhentes fra Svareksponeringsservice XDS Repository Adapter, kaldes Svareksponeringsservicen (se afsnit 6), der rummer laboratoriesvar for patienten. Svareksponeringsservicen returnerer i svarets header en Privacy Information Header (PIH), der beskriver indholdet med henblik på senere samtykkekontrol. PIH'en og laboratoriesvarsdokumentet indlejrer Svareksponerings-service XDS Repository Adapter i et Privacy Information Wrapper-dokument, så DDS'en kun modtager et samlet dokument.
DDS kan identificere, at det returnerede dokument er et PIW og pakke det oprindelige indhold ud. Ud fra PIH'en indeholdt i PIW-dokumentet, foretager DDS om nødvendigt kontrol af data-specifikke samtykker ved at kalde samtykkeverifikationsservicen. Har patienten frabedt sig indsigt foretages frafiltrering og i svaret fra DDS markeres, at der er tilbageholdt information.
Deployment af Svareksponeringsservice XDS-adaptere
I nedenstående deploymentdiagram er Svareksponeringsservice XDS adapterne deployeret i NSP-backoffice. Dette beror på et valg, da de lige så vel kunne være deployeret hos eller tættere på Laboratoriedatabanken.
Figur 3 Deployment af Svareksponeringsservice XDS-adaptere. Opslag på metadata om dokumenter sendes til alle registre kendt af DDS Registry – her XDS Registry og Svareksponeringsservice XDS Registry Adapter. Når dokumenter indhentes på baggrund af metadata returneret fra Svareksponeringsservice XDS Registry Adapter, da hentes dokumenterne fra Svareksponeringsservice XDS Repository Adapter.
Opslag på metadata om dokumenter sendes til alle registre kendt af DDS Registry – her XDS Registry og Svareksponeringsservice XDS Registry Adapter. Når dokumenter indhentes på baggrund af metadata returneret fra Svareksponeringsservice XDS Registry Adapter, da hentes dokumenterne fra Svareksponeringsservice XDS Repository Adapter.
Implementation af Svareksponeringsservice XDS-adaptere
I ovenstående er Svareksponeringsservice XDS-adaptere nedbrudt i logiske komponenter. Disse er implementeret i komponenter navngivet som vist i Tabel 1.
Logisk komponent | Implementation | Funktion |
|---|---|---|
Svareksponerings-service XDS Registry Adapter | sxa-documentmetadataprovider | Returnerer dokumentmetadata |
Svareksponerings-service XDS Repository Adapter | sxa-documentprovider | Kalder Svareksponerings-servicen og pakker returneret dokument ind i wrapper (PIW), der returneres. |
Tabel 1* *Implementation af komponenterne i Svareksponeringsservice XDS-adaptere*
I \[Driftsvejledningen\] er beskrevet konfiguration for Svareksponeringsservice XDS-adaptere, hvor navngivning af property-filer, log-konfigurationsfiler etc. følger navngivningen brugt for implementationen.
Arkitekturbeslutninger
Svareksponeringsservice XDS Registry Adapter
ID | Beskrivelse | Rationale |
|---|---|---|
SES.XDS.Registry.Adapter.Intet.Kald | Opslag på patient skal give dokumentmetadata uden kald af Svareksponeringsservice. | For at minimere svartid på opslag, da dette foretages for alle patienter. |
SES.XDS.Registry.Adapter.Ingen.Persistering.Søgeparametre | Søgeparametre givet ved opslag på patient persisteres ikke til anvendelse på dokumentindhentningstidspunktet. | Fravalg af persistering simplificerer løsning og giver mere frihed mht. deployering. På decentrale NSP må der ikke persisteres. |
SES.XDS.Registry.Adapter.Begrænsede.Søgeparametre | Ikke alle muligheder for angivelse af søgeparametre ved opslag understøttes. Se Tabel 4. | Visse søgeparametre kan relativt let matches mod de metadata, der de facto returneres fra Svareksponeringsservice XDS Registry Adapter og dermed filtreres allerede i opslaget. |
SES.XDS.Registry.Adapter.Encoding.Af.Søgeparametre | Søgeparametre ved opslag bæres videre til indhentning af dokument ved at encode informationen i documentUniqueId/uniqueId. | Dette sker for at undgå persistering mellem opslag og indhentning af dokument. |
SES.XDS.Registry.Adapter.Intet.Patientnavn | Metadata-attributten DocumentEntry.sourcePatientInfo er obligatorisk jf. den danske metadata-profil, som Dokumentdelingsservicen typisk anvendes med. Attributten indeholder patientnavn, kodning af patientens køn samt fødselsdato. | Dokumentanvendere forventes at kende navn ud fra patient-id (cpr-nummeret). |
Tabel 2 Arkitekturbeslutning for Svareksponeringsservice XDS Registry Adapter
Svareksponeringsservice XDS Repository Adapter
ID | Beskrivelse | Rationale |
|---|---|---|
SES.XDS.Repository.Adapter.Datagrundlag.Relation.Parameter | Svareksponeringsservicen har obligatorisk kaldparameter Relation, der beskriver forholdet med bruger og patient.
| |
SES.XDS.Repository.Adapter.PIH.Via.PIW | Laboratoriesvarsdokumentet samt en PIH-varedeklaration, der beskriver dokumentet, indlejres i et Privacy Information Wrapper dokument, der returneres ved indhentning af dokument. | PIW genkendes af Dokumentdelingsservicen, der kan foretage samtykkekontrollen ud fra PIH og foretages filtrering af Svareksponeringsservices-dokumentet. |
Tabel 3 Arkitekturbeslutninger for Svareksponeringsservice XDS Repository Adapter
Håndtering af søgeparametre ved opslag på metadata
Ved dokumentkildes opslag på dokumentmetadata på Dokumentdelingsservicen understøttes en søgevariant benævnt FindDocuments. I Tabel 4 er vist de søgeparametre denne understøtter, hvorvidt de er valgfrie eller krævede, samt om der i FindDocuments understøttes en eller flere værdier for samme søgeparameter.
FindDocuments Query Parameter | Krævet (K)/valgfrit | Kardinalitet (M for mange) | Håndteres af filter på opslag | Encodes i dokumentid | Bæres til kald af Svareksponeringsservice | Filtrering efter kald | Håndteres | Kommentar |
$XDSDocumentEntryPatientId | K | x | x | x | ||||
$XDSDocumentEntryClassCode | M | x | x | Skal indeholde konfigurerbar værdi hvis anført, ellers tomt metadata-resultat | ||||
$XDSDocumentEntryTypeCode | M | x | x | Skal indeholde konfigurerbar værdi hvis anført, ellers tomt metadata-resultat | ||||
$XDSDocumentEntryPracticeSettingCode | M | x | x | x | Er delvist håndteret, idet udvalgte værdier bæres til kaldet af Svareksponeringsservicen. | |||
$XDSDocumentEntryCreationTimeFrom | x | x | Må ikke være anført, ellers tomt metadata-resultat | |||||
$XDSDocumentEntryCreationTimeTo | x | x | Må ikke være anført, ellers tomt metadata-resultat | |||||
$XDSDocumentEntryServiceStartTimeFrom | x | x | x | |||||
$XDSDocumentEntryServiceStartTimeTo | ( x) | ( x) | x | Bruges, hvis $XDSDocumentEntryServiceStartTimeFrom ikke er anført | ||||
$XDSDocumentEntryServiceStopTimeFrom | ( x) | ( x) | x | Bruges, hvis $XDSDocumentEntryServiceStopTimeTo ikke er anført | ||||
$XDSDocumentEntryServiceStopTimeTo | x | x | x | |||||
$XDSDocumentEntryHealthcareFacilityTypeCode | M | ÷ | Er ikke håndteret, men kunne være håndteret ved match mod konfigureret værdi (som de øvrige). | |||||
$XDSDocumentEntryEventCodeList | M | x Der laves konfigurerbart filter på søgeparametre på opslagstidspunktet. | x | Skal indeholde konfigurerbar(e) værdi(er) hvis anført, ellers tomt metadata-resultat | ||||
$XDSDocumentEntryConfidentialityCode | M | x | x | Skal indeholde konfigurerbar værdi hvis anført, ellers tomt metadata-resultat | ||||
$XDSDocumentEntryAuthorPerson | M | x | x | Må ikke være anført, ellers tomt metadata-resultat. Grundet manglende i indhold i svar fra svareksponeringsservice. | ||||
$XDSDocumentEntryFormatCode | M | x | x | Skal indeholde konfigurerbar værdi hvis anført, ellers tomt metadata-resultat | ||||
$XDSDocumentEntryStatus | K | M | x | x | Skal indeholde approved, ellers tomt metadata-resultat | |||
$XDSDocumentEntryType | M | x | x | Skal indeholde On-demand typen, ellers tomt metadata-resultat |
Tabel 4 Håndtering af søgeparametre på opslag. Søgeparametre til FindDocuments er her vist med $XDSDocumentEntryType, der er en tilføjelse fra understøttelse af On-demand dokumenter.
I tabellens kolonne "Håndteres af filter på opslag" er med kryds markeret de søgeparametre, der håndteres af Svareksponeringsservice XDS Registry Adapter på tidspunktet for opslag på dokumentmetadata.
Visse søgeparametre skal, hvis de er anvendt af dokumentanvender, indeholde bestemt værdi. Har en dokumentanvender fx anført værdier for $XDSDocumentEntryType, så skal disse afspejle typen On-demand. Er der kun anført stabile dokumenter vil Svareksponeringsservice XDS-adaptere ikke tilbyde dokument og der skabes et tomt metadata-resultat på opslaget.
Andre søgeparametre, der håndteres på opslagstidspunktet, skal, såfremt dokumentanvenderen har anført værdi(er), indeholde bestemte værdier. Svareksponeringsservice XDS-adaptere returnerer dokument af type laboratoriesvarsdokument, hvorfor det giver mening, at dokumentmetadata returneret fra Svareksponeringsservice XDS-adaptere specificerer denne type. Har dokumentanvenderen søgt på andre typer, kan der returneres tomt metadata-resultatet på opslaget. Søger dokumentanvender på andre dokumenttyper og laboratoriesvarsdokumenttypen, da giver det mening at returnere dokumentmetadata. Dette er generaliseret som et filter, hvor der matches mod et konfigurerbart sæt af værdier, der, hvis de pågældende søgeparametre er anført, skal være blandt anførte værdier (er de ikke konfigureret foretages ingen filtrering på den konkrete søgeparameter).
Tabellens kolonne "Bæres til kald af Svareksponeringsservice" markerer de værdier fra søgeparametre, hvis værdier anvendes ved kaldet af Svareksponeringsservicen. Som nævnt i afsnit 3.1 encodes disse søgeparametre i dokumentid returneret som dokumentmetadata fra Svareksponeringsservice XDS Registry Adapter. Dokumentid anvendes ved indhentning af dokument og derved er de tilgængelige for Svareksponeringsservice XDS Repository Adapter og kan decodes til kald af Svareksponeringsservicen.
I kolonnen "Filtrering efter kald" er med kryds markeret de søgeparametre, hvor der foretages filtrering efter kaldet af Svareksponeringsservicen er foretaget.
I samme kolonne er der med minus markeret de ikke-håndterede søgeparametre, hvor tilsvarende håndtering ville kræve:
- at de blev båret fra metadata-opslag til indhentning af dokument
- at søgeparameter-værdier blev omsat til værdier i data fra Svareksponeringsservicen mhp. filtrering
Som det fremgår af kolonnen "Håndteres", reagerer Svareksponeringsservice XDS-adaptere på dokumentanvenders anførelse af de markerede søgeparametre. Undtaget herfor er $XDSDocumentEntryHealthcareFacilityTypeCode søge-parameteren. Hvis dokumentanvender alene søger efter dokumenter skabt på fx et hospital, da reagerer Svareksponeringsservice XDS-adaptere ikke på det og returnerer metadata og evt. dokument iht. ovenstående.
Design af Svareksponeringsservice XDS-adaptere
Svareksponeringsservice XDS Registry Adapter og Svareksponeringsservice XDS Repository Adapter er baseret på webservice-implementationer for opslag og indhentning af dokumenter tilgængelige i hjælpebiblioteket dk.nsi.documentsharing. Derved er skabelsen af de to adapteres webservicesnitflader reduceret til konfiguration og overholdelse af det framework, der er implementeret i dk.nsi.documentsharing. Svareksponeringsservice XDS-adapterne skal således implementere henholdsvis interfacet DocumentMetadataProvider og DocumentRetriever, der begge bygger på dk.nsi.documentsharing's abstraktioner over XDS.
Svareksponeringsservice XDS Registry Adapter
Det primære udgangspunkt for forståelse af koden er konfigurationen af webservicen, der foretages i maven-artefaktet sxa-documentmetadataprovider-war. Konfigurationen i web.xml udpeger MetadataProviderWS i hjælpebiblioteket, der delegerer ansvaret for at fremskaffe dokumentmetadata til interfacet DocumentMetadataProvider. Svareksponeringsservice XDS Registry Adapter's implementation af dette interface er DocumentMetadataProviderImpl.
Tabel 5 Overordnet design af Svareksponeringsservice XDS Registry Adapter
DocumentMetadataProviderImpl benytter MetadataQueryFilter til at afgøre, om opslagets søgeparametre er forenelige med at returnere dokumentmetadata ud fra konfigurerbare filter-værdier, dvs. om der skal returneres dokumentmetadata eller ej. I \[Driftsvejledningen\] er konfiguration og logik for filteret beskrevet.
Skal dokumentmetadata returneres, skaber DocumentMetadataProviderImpl disse som givet i Tabel 6.
Metadata-attribut | Værdi bestemmes af |
|---|---|
patientId | Query |
sourcePatientId | Query |
UniqueId (DocumentUniqueId) | Encoding af query parametre |
Author.authorPerson | Metadata-konfiguration |
Author.authorInstitution | Metadata-konfiguration |
classCode | Metadata-konfiguration |
confidentialityCode | Metadata-konfiguration |
eventCodeList | Metadata-konfiguration |
creationTime | Null (må ikke anføres for on-demand dokument) |
formatCode | Metadata-konfiguration |
HealthcareFacilityTypeCode | Metadata-konfiguration |
practiceSettingCode | Metadata-konfiguration |
serviceStartTime | Værdi fra query overføres, ellers anvendes patientens fødselsdato, hvis den kan udledes af patientId |
serviceStopTime | Værdi fra query overføres, ellers null |
availabilityStatus | Hardcoded til Available |
typeCode | Metadata-konfiguration |
mimeType | Metadata-konfiguration |
languageCode | Metadata-konfiguration |
homeCommunityId | Metadata-konfiguration |
repositoryUniqueId | Metadata-konfiguration |
title | Metadata-konfiguration |
entryUUID | UUID-repræsentation af uniqueId |
objectType | Hardcoded til On-demand |
Tabel 6 Dokumentmetadata returneret fra Svareksponeringsservice XDS Registry Adapter. Query anfører søgeparametre brugt ved opslaget.
Svareksponeringsservice XDS Repository Adapter
Det primære udgangspunkt for forståelse af koden er her konfigurationen af webservicen, der foretages i maven-artefaktet sxa-documentprovider-war. Konfigurationen i web.xml udpeger DocumentProviderWS i hjælpebiblioteket, der delegerer ansvaret for at fremskaffe dokument(er) til interfacet DocumentRetriever. Svareksponeringsservice XDS Repository Adapters implementation af dette interface er DocumentRetrieverImpl.
Tabel 7 Overordnet design af Svareksponeringsservice XDS Repository Adapter
DocumentProviderImpl kalder Svareksponeringsservicen og indlejrer dokument og PIH returneret derfra i et PIW-dokument. Sidstnævnte er med henblik på at Dokumentdelingsservicen kan gennemføre udpakning, evt. samtykkekontrol og evt. frafiltrering.
Håndtering af datoer
En dokumentanvender kan ved opslag på dokumentmetadata vælge forskellige kombinationer af start- og slut-datoangivelser for behandlingsperiode samt evt. intervaller, som start- og slut-datoer skal ligge inden for. Svareksponeringsservicen understøtter ikke intervaller som inputparametre, hvorfor der i stedet anvendes maksimalt udspændende start- og stop-datoer.
Svareksponeringsservice
Svareksponeringsservicens snitflade er beskrevet i \[SES snitflade\].