Innehållsförteckning

Introduktion

Syfte

Integrationer gjorda genom FHIR behöver liksom övriga integrationer beskrivas utifrån ett antal olika perspektiv. Inera tillhandahåller idag ett antal dokumentmallar med inbördes relation till varandra. Samtidigt tillhandahåller FHIR självt stöd för dokumentation av sina integrationer. Den här vägledningen syftar till att bottna i frågan om hur FHIR-baserade integrationer bäst dokumenteras utifrån vad som redan finns idag inom RIV i former av dokumentationsmallar.

Målgrupp

Primär målgrupp för denna anvisning är personer som arbetar med Ineras tjänsteutveckling, särskilt i de tjänster där FHIR utpekats som en standard som ska användas.
Sekundära målgrupper är personer som arbetar med etablering av FHIR-baserade integrationer ute hos regioner, kommuner, IT-leverantörer samt statliga myndigheter.

ImplementationGuide enligt HL7

“En ImplementationsGuide (IG) är en uppsättning regler om hur FHIR-resurser ska användas för att lösa ett visst problem, med tillhörande dokumentation för att stödja och klargöra användningen.” (fritt översatt från ImplementationGuide - FHIR v4.0.1 (hl7.org)).

IG är en resurs som, liksom alla andra FHIR-resurser, kan hanteras maskinellt. Det betyder att man automatiskt kan generera websidor utifrån dess struktur samt även använda den som källa för validering av resurser i realtid. IG-resursens uppbyggnad gör det möjligt för programkod att inkludera samtliga delar som ingår i en profilering, så som profiler, ValueSets, CodeSystems osv, vid generering av dokumentationen i webformat.

En FHIR-integration måste inte beskrivas genom användandet av IG-resursen men de maskinella stöd som finns för generering av innehåll, anpassat för publicering på webben, gör att det finns goda anledningar att använda den.

En IG underlättar arbetet med profileringar av de resurser som behövs genom att i fältet ImplementationGuide.global peka ut vilka profiler som ska gälla för alla resurser inom IGn om inget annat uttrycks explicit.

I FHIR-standarden beskrivs ett antal attribut som IG-resursen ska innehålla, som t.ex. url, version och name. Ett av attributen är page som definieras enligt följande: En sida / sektion i implementationsguiden. (fritt översatt från ImplementationGuide - FHIR v4.0.1 (hl7.org)). Exakt vilken information en sida eller sektion ska innehålla definieras inte i FHIR-standarden och lämnar därför ett tolkningsutrymme för hur en IG kan utformas.

Sammanfattningsvis är IG-resursen FHIR-standardens egna sätt att underlätta för integratörer att beskriva sina FHIR-baserade API:er och integrationer.

ImplementationGuide enligt Inera

Då FHIR-standarden lämnar ett tolkningsutrymme gällande den exakta utformningen av en IG och dess innehåll finns nedan en beskrivning om hur Inera har valt se på en IG och dess innehåll.

ImplementationGuide som möjliggörare i T2

IG används i FHIR-standarden även som nyckel för att sammanfatta en förmåga som en FHIR-server har. Det får som konsekvens att det mappar väl in mot konceptet digital tjänst i T2. Vid realisering av byggblocket Tjänstekatalog (T2 ref) kan en IGs unika identifierare i form av dess URI användas för att representera det som en tjänsteproducent vill kunna erbjuda sökning på i en Tjänstekatalog. I exemplet på den refererade sidan skulle varje digital tjänst kunna representeras av en unik IG. På så vis skulle tjänsteregistreringen kunna göras helt och hållet utifrån de IG som tagits fram inom informationsfederationen.

Vid behov kan en IG referera till en annan IG. Den mekanismen kan möjliggöra återanvändning av instruktioner som gäller för ett flertal andra IGn. Ett möjligt exempel på detta skulle kunna vara inom området Tidbok, där ett antal IGs tas fram för att representera varje ingående digital tjänst. Alla dessa kan dock ha saker gemensamt, så som säkerhetsrelaterade frågeställningar eller liknande som med fördel kan uttryckas en gång.

Vad bör en ImplementationGuide innehålla?

För att kunna härleda vad en IG bör innehålla för att dokumentera FHIR-integrationer byggda utifrån T2-arkitekturen behöver man se till vilka behov av dokumentation som finns, samt vilka mallar och former för dokumentation som redan används i praktiken idag och som även kan användas vid dokumentation av FHIR-integrationer. Behoven definieras genom byggblocket Interoperabilitetsspecifikation från T2 - vård och omsorg, med sina fyra specialiserande byggblock:

• Legal interoperabilitetsspecifikation

• Organisatorisk interoperabilitetsspecifikation

• Semantisk interoperabilitetsspecifikation

• Teknisk interoperabilitetsspecifikation

För dokumentation av lösningar framtagna utifrån T-bokens arkitektur används en serie av mallar som alla fyller ett visst syfte och har ett visst perspektiv:

• Informationsspecifikation

• Integrationsprofil i form av Tjänstekontraktsbeskrivning

• Tillämpningsanvisning

För ytterligare information om dessa hänvisas till VI-boken. Dessa mallar mappar ganska så väl mot beskrivningen av byggblocken av typen Interoperabilitetsspecifikation:

Informationsspecifikation

“Informationsspecifikationen är oberoende av teknisk realisering. Den är till för att på ett gemensamt och strukturerat sätt beskriva informationsbehovet ur ett verksamhetsperspektiv. Syftet är att informationen blir förberedd för elektronisk hantering på ett gemensamt och standardiserat sätt.

Innehåll och struktur för informationsspecifikationen beskrivs vidare i Mall för Informationsspecifikation.”

Citatet ovan är taget från VI-boken och vägleder oss i förståelsen av vad Informationsspecifikationen har för syfte och vad den innehåller. Då Informationsspecifikationen fortsatt har en naturlig plats i T2-baserade integrationer kan ett resonemang föras att inget av det som idag täcks in av den mallen behöver dokumenteras i en ImplementationGuide. Informationsspecifikationen kompletterar således ImplementationGuiden.

Integrationsprofil i form av Tjänstekontraktsbeskrivning

“Integrationsprofilen är en teknisk specifikation som beskriver syntaktisk realisering av informationsspecifikationen och används när det finns behov av att utbyta informationen mellan två eller fler aktörer. Integrationsprofilen är en kravspecifikation. Den skall fungera som ett teknikneutralt, formellt regelverk som reglerar integrationskrav för parter (tjänstekonsumenter och tjänsteproducenter) som avser ansluta system för samverkan enligt dessa integrationsprofiler.

Inom RIVTA Basic Profile 2.1 används tjänstekontraktsbeskrivningar (TKB) som integrationsprofiler. Där är de ett viktigt underlag för skapande av de tekniska kontrakten (scheman och WSDL-filer).”

Citatet ovan är taget från VI-boken och vägleder oss i förståelsen av vad Integrationsprofil i form av Tjänstekontraktsbeskrivning har för syfte och vad den innehåller. Eftersom HL7 FHIR kan likställas med att vara en annan profilering än RIVTA Basic Profile 2.1, och Tjänstekontraktsbeskrivningen är en mall framtagen för att beskriva just den typen av integrationsprofiler är den inte lämplig att använda för att dokumentera en FHIR-integrationsprofil. Inom FHIR används istället ImplementationsGuide.

Tillämpningsanvisning

“Tillämpningsanvisningen är till för att ge ytterligare beskrivning för tjänstekontrakt som adresserar ett flerdelat verksamhetsområde. Tillämpningsanvisningen beskriver hur tjänstekontraktet ska tillämpas för att fånga olika typer av informationsmängder inom samma verksamhetsområde. I tillämpningsanvisningen beskrivs restriktioner för aktuella informationsmängder i anrop och/eller svar.”

Citatet ovan är taget från VI-boken och vägleder oss i förståelsen av vad Tillämpningsanvisning har för syfte och vad den innehåller. Utifrån ett FHIR-perspektiv hanteras det här behovet automatiskt genom standardens mekanismer för profilering. Därför kommer ingen separat dokumentation krävas för att lösa det behovet när man realiserar samverkan via FHIR-standarden.

OBS! Sedan VI-boken 2021:1 publicerades har en begreppsförändring skett, och det som kallades Tillämpningsanvisning där har inom RIV-TA ersatts med Interaktionsöverenskommelse. Innehållet i mallen är dock detsamma, och skrivningen i VI-boken förändras inte förutom på rubriknivå.

Scope för ImplementationGuide enligt Inera

En ImplementationGuide bör således avgränsas från att beskriva de semantiska och verksamhetsmässiga delarna som redan fångas i en Informationspecifikation. En IG behöver däremot bära information om den syntaktiska realiseringen av informationen som beskrivs i Informationsspecifikationen. Lite mer konkret innebär det att den behöver samla de profilerade resurserna med sina tillhörande kodsystem, extensions etc.

Utöver det kan den även fungera som bärare av de krav som ställs på en FHIR-server som ska ingå som part i informationsutbytet. I förlängningen blir det även en kravställare på FHIR-klienten som anropar FHIR-servern.

ImplementationGuiden har som roll att även beskriva de steg som en FHIR-klient behöver ta för att nå fram med sina anrop mot FHIR-servern. Det inkluderar anrop till relevanta infrastrukturtjänster och anropsmönster som ska appliceras mot dess infrastrukturtjänster. På samma sätt behöver FHIR-serverns förpliktelser beskrivas.

Ett exempel på innehållet som bör finnas i en IG, på rubriknivå, finns att ta del av (länk till sidan med “mallen”).

Sammanfattning

En IG ska tas fram för varje digital tjänst som behöver vara sökbar i en Tjänstekatalog. Den ska innehållsmässigt komplettera Informationsspecifikationen på samma sätt som en Tjänstekontraktsbeskrivning kompletterar Informationsspecifikationen i en RIVTA Basic Profile 2.1-integration.

IG som tas fram inom Inera ska minst innehålla den information som finns listad i mallen för ImplementationGuide.