TODO: titel? 

links til gavn under skrivning:

Teknisk implementeringsvejledning Aftaleoversigt

Aftaler

https://github.com/KvalitetsIT/kih-anvendelse

https://github.com/KvalitetsIT/aftaledeling

NXRG - Design- og arkitekturbeskrivelse

Indledning

Formål

Dokumentdeling gør det muligt for aktører sundhedsvæsnet at dele relevante data om borgere, og dermed skabe et overblik over den enkelte borgers situation for de aktører som har brug for dette. Det kan være dem, som planlægger og gennemfører behandlingsforløb eller for borgerens selv og omsorgspersoner. Samtidig skal det være muligt for borgeren at bestemme, hvem han/hun vil dele disse data med gennem samtykke samt se, hvem der har læst data via MinLog. Infrastrukturen der muliggør deling af dokumenter på tværs af sundhedsaktører er baseret på IHE XDS standarden

Dette dokuments fokus er selve dokumentdelingen; dens dele, dens infrastruktur og hvordan man kommer igang med at anvende den som eksempelvis udvikler, der skal udvikle systemer der skal anvende den.

Der forventes et hvis kendskab til CDA dokumenter - da fokus ikke er disse, ligesom kendskab til anvendelse af DGWS, NSP og SDN  forventes. Hjælpe moduler som MinSpæring, MinLog og andre komponenter, der er i spil i forbindelse med dokumentdeling berøres heller ikke andet overfladisk.

Hvad er dokumenter

Data i en XDS infrastruktur gemmes som dokumenter. Et dokument har et unikt id (documentId) og en række metadata, der beskriver, hvad dokumentet handler om. Dokumenter kan indholdsmæssigt være af flere forskellige typer: PDF, Word-dokument, men kan også være af typen CDA (Clinical Document Architecture). Et CDA dokument er egentlig bare et struktureret XML dokument, der følger en bestemt standard for kliniske dokumenter til udveksling (deling). Se f.eks. What is HL7 CDA? for en kort beskrivelse. Her kan man bl.a. se, at CDA findes på forskellige niveauer 1-3, hvor 3 har den højeste grad af struktur.

En vigtig egenskab ved CDA dokumenter er den fælles CDA header. Denne header indeholder information, der går igen henover alle typer af kliniske dokumenter f.eks. hvilken patient drejer dokumentet sig om, hvilken organisation er ansvarlig (ejer) af dokumentet mm. CDA headeren er således en international standard (HL7), men der findes en dansk specialisering af denne (standardiseret i regi af Medcom). Denne er beskrevet her HL7 Implementation Guide for CDA Release 2.0 CDA Header (DK CDA Header). Medcom vedligeholder en liste over tilladte værdi sæt for metadata, som findes her DK-IHE_Metadata-Common_Code_systems-Value_sets.

Der findes andre profiler, der er specialiseringer af CDA. Dvs. kliniske dokumenter, der har en struktur til bestemte formål. Medcom har leveret danske profileringer af følgende typer (se evt. Medcoms oversigt over HL7 standarder):

• Appointment Document (APD) til aftaler
• Careplan (CPD)
• Personal Data Card (PDC)
• Personal Health Monitoring Report (PHMR) til hjemmemonitorering
• Questionnaire Form Definition Document (QFDD) og Questionnaire Response Document (QRD) til patientrapporterede oplysninger (PRO)

Oprindelig var det aftaledokumenter (APD) som blev delt på NSP platformen. Men det har ændret sig, så også de andre dokumenttyper er kommet i spil. Alle dokumenterne på NSP er CDA dokumenter for nuværende. Og de skal alle overholde Medcoms profiler nævnt ovenfor. 

Der er to typer af CDA dokumenter (angives også i metadata feltet type) .

• "Stable document" som bliver skabt og gemt en gang for alle
• "On-demand" som først skabes på det tidspunkt det faktisk efterspørges

TODO: andre dokumenttyper af ondemand som skal nævnes med navn?

Hvad er dokumentdeling

XDS står for Cross-Enterprise Document Sharing og er en international standard udarbejdet af Integrating the Healthcare Enterprise (IHE) for udveksling af kliniske dokumenter. En XDS infrastruktur består (mindst) af følgende to komponenter:

• XDS Repository: Står for persistering af dokumenter tilknyttet et unikt ID.
• XDS Registry: Står for opbevaring og indexering af metadata vedr. dokumenterne i et eller flere XDS repositories. Dette kunne f.eks. være start- og sluttidspunkt dokumentet dækker over, eller dets forfatter (author) (oplysningerne stammer fra CDA headeren)

Integrationen med XDS infrastrukturen sker vha en række standardiserede SOAP webservices - ITI kald. Et overblik over XDS infrastrukturen og de forskellige services ses nedenfor:

Når data skal deles vha XDS sker følgende:

1. Dokumenter afleveres af dokumentkilden (Document Source) til XDS repository via servicehåndtaget ITI-41 Provide and Register Document Set. Herefter sørger XDS repository for at registrere dokumentet i XDS registry via servicehåndtaget ITI-42 Register Document Set.
2. Hvis der er tale om et on-demand dokument registreres det af dokumentkilden (On Demand Document Source) direkte i XDS registry via servicehåndtaget ITI-61 Register On Demand Document Entry,  da der ikke et et faktisk CDA dokument at gemme.
3. Dokumentaftager (Document Consumer) fremsøger dokumenter i XDS registry via servicehåndtaget ITI-18 Registry Stored Query. Svaret på denne query er en liste af documentIds og repositoryIds, der fortæller, hvilke dokumenter der lever op til søgekriterierne, og hvor de findes (repositoryId)
4. Dokumentaftager (Document Consumer) henter dokument i XDS repository via servicehåndtaget ITI-43 Retrieve Document Set
5. Dokumentadministrator (Document Administrator) kan opdatere metadata (heriblandt deprecate) i XDS registry via servicehåndtaget ITI-57 Update Document Set.
6. (Patient Identify Source som fremgår af figuren anvendes ikke på NSP)

IHE XDS standarden er specificeret i en række dokumenter: 

Hvis man skal igang med dokumentdeling, og ingen kendskab har til ovenstående specifikationer, kan en tilgang være:

• Start med at skabe et overblik over documententry, associations og submissionsest - f.eks. i "ITI TF-3 afsnit 4.1 Abstract Metadata Model"
• Læs derefter omkring ITI-41 til oprettelse/ret af dokumenter - ITI TF-2 afsnit "3.41 Provide and Register Document Set-b [ITI-41]"
• Og læs derefter omkring ITI-18 fremsøgning af dokumenter : ITI TF-2 afsnit "3.18 Registry Stored Query [ITI-18]"
• Og herefter om ITI-43 hent af dokumenter: ITI TF-2 afsnit "3.43 Retrieve Document Set [ITI-43]"

Arkitekturoversigt af komponenter

På NSP består dokumentdelings infrastrukturen af følgende komponenter.

<< oversigtstegninger over komponenter og iti interaktioner - tag kopi fra aftaledeling: Aftaler - justser med (+SFSK og -backends)?? >> I den tegning for dokumentdeling er det DDS Repo+Registry+DRS+DROS+SFSK, der er relevante (diverse backends skal ikke dokumenteres her). Skrive "udløbsdato" for DRS.

<< liste og forklaring af tegning inkl links til anvender guide for de forskellige >>

husk at placere hjælpe moduler og nævne at det får man med 

nævne flere miljøer med denne konfig, og ref'e til test link nedenfor

Minlog, behandlingsrelationer, minSamtykke (filter) og værdispring

Hvordan kommer man igang

Komponenterne i dokumentdelings infrastrukuren kommunikerer med ITI kald, som er standardiserede SOAP services, der skal overholde IHE XDS specifikationen. De er i det såkaldte XML basererede "RIM format"

Det er op til anvenderen/udvikleren selv at vælge platform og frameworks, der passer til resten af dennes løsning. Fra et udvikler perspektiv kan man enten vælge selv at generere stubkode udfra de standardiserede WSDL filer eller at anvende et tredjepartsprodukt.  Nedenfor gives et forslag til, hvordan det kan gribes an med tredjepartsproduktet IPF Open eHealth Integration Platform, som forudsætter man arbejder på en java platform. Andre platforme kan have tilsvarende værktøjer og muligheder.

Da dokumentdelingen kører på NSP og sundhedsdatanettet (SDN) skal man anvende Den gode Web Service og have adgang til SDN for den del af miljøerne. Dette beskrives ikke yderligere her.

OpeneHealth biblioteket til Java

Man behøver ikke at basere alting på Camel, men kan med fordel nøjes med at inkludere biblioteket IPF Commons IHE XDS i sin kodebase. Her findes både stubbe og en masse anvendelige utilities. Disse kan blandt andet mappe fra RIM formatet til en en "OpeneHealth core model", som er java klasser. Og gør det at udvikle ITI kald lettere at arbejde med.

Helt overordnet kan det at lave et ITI kald deles op i følgende trin

1. Opret kald i OpeneHealth code model
   1. For ITI41 kald indebærer det blandt andet opret/indlæs af dokument samt opret af metadata til documententry
   2. For ITI42, 57 og 61 indebærer det oprettelse af metadata
   3. For ITI18 skal søge kriterierne sættes op
   4. For ITI43 skal dokumentiderne sættes op
2. Udfør kald - det transformeres til RIM formatet på vej ud, og tilbage til core model ved returnering automatisk vha. openeHealth frameworket
3. Aflæs kaldets svar og håndter eventuelle fejl returneret. For ITI-18 og ITI-43 er der ligeledes dokument id'er henholdsvis dokumenter, der skal håndteres.

Dette kan illustreres ved følgende transformeringsdiagram, hvor man ser core modellen blive transformateret til RIM formatet og efterfølgende et ITI kald udført. Resultatet af ITI kaldet kommer tilbage i RIM format, og transformeres til core modellen:

Et eksempel på, hvordan forskellen mellem core model og RIM format kommer til udtryk, ses her for håndtering af confidentiality code og CPR nummer i forbindelse med oprettelse af et dokument.

Først OpeneHealth core model, den kode man skriver i sit program:

documentEntry.getConfidentialityCodes().add(new Code("N", new LocalizedString("N"), "2.16.840.1.113883.5.25"));

AssigningAuthority patientIdAssigningAuthority = new AssigningAuthority("1.2.208.176.1.2");
Code patientCode = new Code("2512489996", new LocalizedString("CPR"), "1.2.208.176.1.2");
documentEntry.setPatientId(new Identifiable(patientCode, patientIdAssigningAuthority));

Og her tilsvarende RIM format, som openeHealth automatisk oversætter det til og som anvendes ved ITI kaldet:

<ns2:Classification classificationScheme="urn:uuid:f4f85eac-e6cb-4883-b524-f2705394840f" classifiedObject="urn:uuid:69d3b9f3-7919-40e0-8731-32fb339216c2" nodeRepresentation="N" id="urn:uuid:9068bc2b-1717-4337-abfb-027f303b20c6">
  <ns2:Slot name="codingScheme">
    <ns2:ValueList>
      <ns2:Value>2.16.840.1.113883.5.25</ns2:Value>
    </ns2:ValueList>
  </ns2:Slot>
  <ns2:Name>
    <ns2:LocalizedString xml:lang="en-US" charset="UTF-8" value="N"/>
  </ns2:Name>
</ns2:Classification>

<ns2:ExternalIdentifier registryObject="urn:uuid:69d3b9f3-7919-40e0-8731-32fb339216c2" identificationScheme="urn:uuid:58a6f841-87b3-4a3e-92fd-a8ffeff98427" value="2512489996^^^&1.2.208.176.1.2&ISO" id="urn:uuid:6dc240d8-d871-4df1-b8c6-3414f1415022">
  <ns2:Name>
    <ns2:LocalizedString value="XDSDocumentEntry.patientId"/>
  </ns2:Name>
</ns2:ExternalIdentifier> 

Det følgende er eksempelkode til at illustrere et ITI-41 kald til oprettelse af et dokument

// Nyt kald/request 
ProvideAndRegisterDocumentSet provideAndRegisterDocumentSet = new ProvideAndRegisterDocumentSet();

// Opret documentEntry
DocumentEntry documentEntry = new DocumentEntry();
AssigningAuthority patientIdAssigningAuthority = new AssigningAuthority("1.2.208.176.1.2"); // OID for CPR registret
Identifiable patientIdentifiable = patientIdentifiable = new Identifiable("2512489996", patientIdAssigningAuthority);
documentEntry.setPatientId(patientIdentifiable);
... mere metadata, se CDA profilen

// Tilføj dokumentet til request
provideAndRegisterDocumentSet.getDocuments().add(new Document(documentEntry, new DataHandler(new ByteArrayDataSource(documentPayload.getBytes(), documentEntry.getMimeType()))));

// Opret SubmissionSet
provideAndRegisterDocumentSet.setSubmissionSet(createSubmissionSet(documentEntry.getPatientId(), contentTypeCode, submissionTime));

// Opret association mellem SubmissionSet og DocumentEntry
provideAndRegisterDocumentSet.getAssociations().add(createAssociation(submissionSet, documentEntry));

// Transformer request - dette laver core model om til RIM format
ProvideAndRegisterDocumentSetTransformer registerDocumentSetTransformer = new ProvideAndRegisterDocumentSetTransformer(ebXMLFactory);
EbXMLProvideAndRegisterDocumentSetRequest30 ebxmlRequest = (EbXMLProvideAndRegisterDocumentSetRequest30) registerDocumentSetTransformer.toEbXML(provideAndRegisterDocumentSet);
ProvideAndRegisterDocumentSetRequestType provideAndRegisterDocumentSetRequestType = ebxmlRequest.getInternal();

// Udfør kald
RegistryResponseType registryResponse = iti41PortType.documentRepositoryProvideAndRegisterDocumentSetB(provideAndRegisterDocumentSetRequestType);

// Transformer response - dette laver RIM format til core model
ResponseTransformer responseTransformer = new ResponseTransformer(ebXMLFactory);
Response response = responseTransformer.fromEbXML(new EbXMLRegistryResponse30(registryResponse));

// Aflæs kaldets svar
if (response.getStatus().equals(Status.SUCCESS.getOpcode30())	) {
	// Kaldet gik godt
} else {
	// Der er fejl i kaldet, håndter dem
	for (RegistryError error : response.getRegistryErrorList().getRegistryError()) {
	}
} 

(Det er flere detaljer omkring ITI-41 eksempelkode i anvender guiden til DROS.)

TODO map til tegning

Et tilsvarende eksempel for ITI-18 fremsøgning kunne se således ud:

// Nyt kald/request 
FindDocumentsQuery findDocumentsQuery = new FindDocumentsQuery();

// Opret søge kriterier
AssigningAuthority patientIdAssigningAuthority = new AssigningAuthority("1.2.208.176.1.2"); // OID for CPR registret
Identifiable patientIdentifiable = patientIdentifiable = new Identifiable("2512489996", patientIdAssigningAuthority);
findDocumentsQuery.setPatientId(patientIdentifiable); // angiv patienten dokumenterne vedrører

List<AvailabilityStatus> searchStatusList = new LinkedList<AvailabilityStatus>();
searchStatusList.add(AvailabilityStatus.APPROVED);
findDocumentsQuery.setStatus(searchStatusList); // søg efter dokumenter, som har status approved

findDocumentsQuery.getServiceStartTime().setFrom(serviceStartTimeFrom); // søg efter specifik dato interval som start tidspunkt
findDocumentsQuery.getServiceStartTime().setTo(serviceStartTimeTo);     // ved at angive fra og til serviceStartTime

QueryRegistry queryRegistry = new QueryRegistry(findDocumentsQuery);
queryRegistry.setReturnType(QueryReturnType.LEAF_CLASS); //returner fuld metadata for de fremsøgte dokumenter

// Transformer request - dette laver core model om til RIM format
QueryRegistryTransformer requestTransformer = new QueryRegistryTransformer();
EbXMLAdhocQueryRequest30 ebxmlRequest = (EbXMLAdhocQueryRequest30) requestTransformer.toEbXML(queryRegistry);
AdhocQueryRequest adhocQueryRequest = ebxmlRequest.getInternal();

// Udfør kald
AdhocQueryResponse adhocQueryResponse = iti18PortType.documentRegistryRegistryStoredQuery(adhocQueryRequest);

// Transformer response - dette laver RIM format til core model
QueryResponseTransformer responseTransformer = new QueryResponseTransformer(ebXMLFactory);
EbXMLQueryResponse ebXML = new EbXMLQueryResponse30(adhocQueryResponse);
QueryResponse queryResponse = responseTransformer.fromEbXML(ebXML);

// Aflæs kaldets svar
if (queryResponse.getStatus().equals(Status.SUCCESS.getOpcode30())	) {
	// Kaldet gik godt, håndter de fremsøgte dokumenter metadata
	for (DocumentEntry documentEntry : queryResponse.getDocumentEntries()) {
	}
} else {
	// Der er fejl i kaldet, håndter dem
	for (RegistryError error : response.getRegistryErrorList().getRegistryError()) {
	}
}  

evt. request resspone 

eksempler på brug af librariet (hvilke objekter og hvilke id'er skal man tage stillinger)

ise det resulterende "RIM XML" så man forstår sammenhængen.

noget af det kan tages dros anvender guide

evt nævn logiske id'er og hvad der sker hvis man tror man sender et uuuid men ikke gør.

gode steder at kigge: integrationstestene  og anvender guides for komponenterne

husk at nævne overholdes af medcom standard for metadata i documententry

Biblioteker til .Net

Hjælpeværktøjer og links

De følgende links kan alle bidrage til at lette arbejdet med at implementere dokumentdeling.