Open	Vägledning: Skapa interoperabilitetsspecifikation   Revision A ARK_0075 2024-12-10

Begrepp och förkortningar

1. Om interoperabilitetsspecifikation

En interoperabilitetsspecifikation ska beskriva syftet med det informationsutbyte som regleras av interoperabilitetsspecifikationen. Detta sker ofta naturligt i samband med att de legala och organisatoriska perspektiven presenteras.

I interoperabilitetsspecifikationen beskrivs de krav som ställs på den part som ska ansluta till en samverkan och som parten förväntas uppfylla. Specifikationen kan vara uppdelad i flera typer av dokument och format. Det är viktigt att alla delar i specifikationen går att låsa för en formell versionshantering. Referenser till externa specifikationer eller dokument ska vara angivna med version för spårbarhet.

En Interoperabilitetsspecifikation kan anses ha stora likheter med till exempel de nationella tjänstkontraktsbeskrivningarna gällande innehåll. Men skillnaderna är främst att Interoperabilitetsspecifikationen har en tydligare uppdelning i fyra vyer samt att den tekniska vyn inte är låst till SOA/SOAP baserade API:er

Det är viktigt att det beskrivs hur bakåtkompabilitet och livscykelhanteringen av Interoperabilitetsspecifikationen ska gå till, inte minst vad gäller versionsuppdateringar av API:er och avveckling av befintliga versioner, så att de parter som ingår vet vad som förväntas av dem när det kommer till krav på följsamhet vid förändring.

Interoperabilitetsspecifikationen ska förses med en unik identifierare som kan användas som bas när man ska referera till denna och till de API:er som beskrivs under den tekniska specifikationen vid sökning efter ett visst API i en tjänstekatalog. Identifieraren behöver alltså vara unik inom den kontext där den ska användas, till exempel inom en tjänstekatalog, hur man säkerställer att identifieraren är unik beror på kontexten.

Interoperabilitetsspecifikationen är, utöver en inledning som övergripande beskriver syftet och omfattningen av samverkan, uppdelad på fyra olika vyer som var och ett beskriver förutsättningar för interoperabiliteten utifrån olika perspektiv.

Open

Struktur för en interoperabilitetsspecifikation

Tillvägagångsättet för att ta fram en interoperabilitetsspecifikation kan variera.

Innehållet kan antingen utarbetas från grunden eller tas från befintliga dokument från tidigare arbete, till exempel en befintlig informationsspecifikation, tjänstekontraktsbeskrivning eller liknande. Om man utgår från information i befintliga dokument så behöver man överväga om information refereras eller inkluderas. Lämpligast är troligen att inkludera den om man inte här helt säker på att en referens kommer vara persistent och är versionshanterad.

VI-boken hos Inera beskriver en metod för att ta fram innehållet för den Legala, Organisatoriska och Semantiska vyn men ger begränsat stöd för den tekniska vyn eftersom den idag är avgränsat till tjänstekontrakt och RIV-TA basic profile

2. Legal vy

Det här avsnittet ska ha fokus på den legala interoperabiliteten. Här beskrivs hur tjänstekonsumenter, tjänsteproducenter och digitala tjänster måste förhålla sig till tillämpliga lagrum och de legala förutsättningarna att utbyta information inom dessa lagrum.

I det här avsnittet beskrivs de tolkningar av lagar och policyer som varje part som utbyter information enligt interoperabilitetsspecifikationen förbinder sig att följa.

En interoperabilitetsspecifikation kan inte beskriva flera syften till samverkan om dessa syften ligger inom olika lagrum.

Exempel: en federation ska inte omfatta både syftet sammanhållen journalföring och invånarens direktåtkomst eftersom det ställs olika krav för uppfyllnad av lagkrav, exempelvis hantering av spärr kontra försegling, för målgrupperna.

3. Organisatorisk vy

Den organisatoriska delen av specifikationen ska beskriva de involverade parterna samt krav på dessa utifrån ett verksamhetsperspektiv. Fokus ska ligga på de processer, policyer samt regelverk som anslutande part behöver leva upp till.

Beskrivningen ska vara på den detaljnivå som krävs för att en ansluten part ska förstå de krav som ställs på denne samt vilka krav den kan ställa på andra anslutna parter.

Det som dokumenteras här är naturligtvis beroende på vad specifikationen avser att stödja. Det är stor skillnad på processpåverkan om specifikationen avser att stödja exempelvis e-remissprocessen eller om den ska stödja situationen kring informationsförsörjning av sammanhållen journalföring.  

Exempel på det som behöver beskrivas i den organisatoriska vyn är:

• Arbetsflöden och processer

• Aktörer och deras roller i arbetsflöden och processer

4. Semantisk vy

Den semantiska delen av specifikation ska fokusera på informationsmodell och kodverk utifrån ett verksamhetsperspektiv.

Informationsmodellen ska fokusera på den information som ska utbytas och hur denna ska tolkas utifrån verksamheten.

Innehållet i den semantiska delen kopplas senare mot det tekniska överföringsformat som väljs för att paketera informationen vid överföring till annat system. Detta görs via API specifikationer och i dessa kan det tillkomma information som behövs för paketering och överföring.

Det tekniska överföringsformatet beskrivs i den tekniska vyn som en del av API-specifikationen. Exempel på tekniskt överföringsformat är HL7 FHIR. 

Exempel på innehåll:

• Meddelandemodeller (MIM)

• Kodverk

• Datatyper

• Formateringsregler

5. Teknisk vy

Den här delen har fokus på den tekniska interoperabiliteten. Specifikationen beskriver de tekniska kraven för informationsutbyte.

Specificerar kraven utifrån tekniskt perspektiv som lämpligen utgår från en målarkitektur eller motsvarande.

Nedanstående punkter är viktiga att beskriva:

5.1 API:er

Man behöver redogöra för de API:er som ska nyttjas för samverkan samt hur dessa används. API:erna i sig behöver vara beskrivna i en för standarden lämplig form - till exempel i form av:

• Tjänstekontraktsbeskrivning (TKB) för nationella tjänstekontrakt enligt Basic Profile 2.1

• Implementationsguide för FHIR-baserade API:er

• Open API-specifikation för andra REST-API:er

API-specifikationer kan vara specifikt framtagna för en specifik interoperabiltetsspecifikation, eller höra till externt förvaltade API:er. Specifikationer ska alltid refereras till med version oavsett om de är federationens egna eller externa.

Alla API:er ska förses med en identifierare som tillsammans med interoperablitetsspecifikationens övergripande id gör det möjligt att i en tjänstekatalog unikt identifiera att ett API är av en viss typ uppfyller villkoren.

Exempel på struktur för identifierare för en viss typ av API:

 <interopspecId>:<APIId>

Identifieraren för "API 1" i skissen som finns in inledningen och som visar strukturen för en interoperabilitetsspecifikation skulle alltså bli:

REMISSV1:SEND1

Denna identifierare kan därefter användas som referens både vid designarbete och när en aktör registrerar sitt API i en tjänstekatalog. Hur man säkerställer att identifieraren är unik och om den ska vara unik inom en snäv kontext eller om den behöver vara unik inom en nationell/bredare kontext är en fråga och beslut som ligger utanför denna vägledning.

5.2 Tekniska stödtjänster

Med tekniska stödtjänster avses här funktioner som inte direkt hanterar den verksamhetsmässig informationen utan avser i stället tjänster som används för att underlätta informationsutbytet mellan parterna.

Stödtjänster kan vara antingen federationsspecifika och då skapas och underhållstjänsterna och deras API-specifikationer av federationen

Alternativt så kan det vara externa tjänster som tillhandahålls av en annan aktör och då hänvisas till deras API-specifikationer. Hänvisning ska då innehålla version och det måste finnas klarhet kring den andra aktörens regler för krav på följsamhet gällande livscykelhantering för stödtjänsten.

Exempel på tekniska stödtjänster som ofta kan behövas och som pekas ut T2 referensarkitekturen är:

• Tjänstekatalog

  • Erbjuder förmågan att se vilka aktörer som har relevanta tjänster samt medger översättning från logiska adresser till tekniska anslutningsadresser (urler)

• Federationsmedlemskatalog

  • Erbjuder förmåga för federationens medlemmar att validera om en annan part är medlem i federationen och vilka eventuella roller den parten har

• Metadatakatalog för identitet och åtkomst

  • Erbjuder förmågan att hämta information om identiteter och behörighetsgrundande attribut.

5.3 Verksamhetsmässiga stödtjänster

Verksamhetsmässiga stödtjänster avser funktioner som avser att styra hur information ska hanteras eller för att berika information.

Exempel på verksamhetsmässiga stödtjänster är:

• Personuppgiftstjänst

• Spärrtjänst 

5.4 Säkerhet

I T2 välfärden ges vägledning i vilka ramverk och standarder som man rekommenderas förhålla sig till och även övergripande beskrivning av de ställningstaganden man behöver ta i beslut om hur man utformar sina ramverk för tillit och säkerhet i samband med att man ska realisera samverkan. se T2 välfärdens och avsnittet tillit och säkerhet för fördjupning inom området.

• Informationssäkerhet behöver beskrivas utifrån hur adekvat säkerhet för samverkan avseende hantering av tillit, identitet, åtkomst, spårbarhet, med mera ska hanteras.

• Man bör också, utifrån informationens skyddsvärde, beskriva vilka nivåer som behövs för ett adekvat dataskydd.

5.5 SLA

Krav på servicenivåer (SLA) för aktörer som ingår i samverkan behöver beskrivas.

5.6 Övrigt

Utöver det som beskrivs ovan så kan det beroende på lösningens utformning behövas beskrivningar av:

• Adresseringsmodell, till exempel:

  • Användning och identifierare för logisk adressering

  • Användning av tjänstekataloger för adressering          

• Felhantering

• Övriga tillämpningsspecifika krav.

• Väsentliga arkitekturella beslut, exempelvis

  • Avsteg från referensarkitekturer

  • Andra strukturella beslut som har väsentlig påverkan på lösningsdesign