RIV Tekniska Anvisningar Tjänsteplattform Version 2.0 ARK_0034 2024-09-18

Innehållsförteckning

1. Inledning

Tjänsteplattformar skapar förmågan för tjänstekonsumenter att nå tjänsteproducenter, med stöd av logisk adressering, via en teknisk anslutning. Tjänsteplattformar förekommer dels i en nationell instans (NTjP), men även hos regionala aktörer inom hälso- och sjukvårdssektorn. För att underlätta bred samverkan kan tjänsteplattformar kopplas ihop.

Tjänstekonsumenter och tjänsteproducenter ansluts till någon av dessa tjänsteplattformar. Tjänsteplattformarna hanterar därefter adressering via vägval, samt åtkomsthantering via anropsbehörigheter för att förmedla informationen.

För samverkan via någon av de förvaltningsgemensamma tjänster som förmedlas via NTjP behöver tjänsteproducenter och tjänstekonsumenter, eller den tjänsteplattform som de är anslutna till, vara anslutna till den nationella instansen. Det behövs även konfiguration för behörighet och logisk adressering.

Detta dokument beskriver regelverket för RIV Tekniska Anvisningar Tjänsteplattform.

Hälso- och sjukvårdssektorn i Sverige har på uppdrag av Sveriges Kommuner och Regioner och under ledning av Inera, gemensamt tagit fram en nationell teknisk arkitektur i syfte att stödja samarbete över organisationsgränserna.

Enligt referensarkitekturen T-boken är en tjänsteplattform en samling komponenter som används för tjänstebaserad kommunikation över huvudmannagränser. En tjänsteplattform agerar kontaktpunkt för anslutningar till och från andra organisationer.

Inera AB har utvecklat en tjänsteplattform kallad SKLTP, som är baserad på öppna programvaror. SKLTP används av den nationella tjänsteplattformen, och är även fritt tillgänglig att användas regionalt. Tjänsteplattformar kan realiseras med valfri programvara såvida reglerna i detta dokument kan uppfyllas.

1.1 Målgrupp

Målgruppen för detta dokument är lösningsarkitekter och utvecklare som ska realisera en tjänsteplattform enligt T-boken och RIV Tekniska Anvisningar.

1.2 Syfte

Syftet med dokumentet är att underlätta utvecklings- och valideringsinsatser genom att samla de krav och regler som ställs på en tjänsteplattform och dess komponenter.

1.3 Tillgänglighet

Detta dokument är publicerat under licensen Creative Commons CC-BY-SA (http://creativecommons.org/licenses/by-sa/2.5/se/ ).

Det betyder att du fritt får kopiera, distribuera och skapa bearbetningar av anvisningarna under förutsättning att upphovsmannen Sveriges Kommuner och Regioner anges, men inte på ett sätt som antyder att de godkänt eller rekommenderar din användning av verket.

1.4 Avgränsningar

Denna anvisning beskriver enbart tekniska regler. Därmed utelämnas ämnen som t.ex. godkännandeprocess kring tjänstekontrakt och krav på loggning.

1.5 Fallstudier

Det finns en referensimplementation av en tjänsteplattform - (SKLTP - Confluence (atlassian.net)). Denna referensimplementation förvaltas aktivt och utgör grunden för den förvaltningsgemensamma tjänsteplattformen Nationell tjänsteplattform (NTjP).

Det har även gjorts ett antal regionala implementationer av tjänsteplattformar av den typ som beskrivs i detta dokument. För ytterligare erfarenhetsutbyte kring dessa, kontakta respektive regions tjänsteplattformsförvaltning.

2. Terminologi

För beskrivning av termer se RIV Tekniska Anvisningar SOAP Webservices.

3. Informationsutbyte via tjänsteplattformar

Nedan beskrivs hur en tjänsteplattform ska hantera logisk adressering och anropsbehörigheter, både fristående och i samverkan med andra plattformar.

3.1 Logisk adressering

Tjänstekonsumenter skickar alltid sina meddelanden till den tjänsteplattform tjänstekonsumenten är ansluten till och adresserar meddelandet med mottagarens logiska adress. Om den logiska adressen finns i den anropade tjänsteplattformens tjänsteadresseringskatalog vidarebefordrar tjänsteplattformen meddelandet till den tekniska anslutningsadress som är knuten till den logiska adressen. Anslutningsadressen kan antingen representera faktiska tjänsteproducenten eller en annan tjänsteplattform. I det senare fallet upprepas processen tills den faktiska tjänsteproducenten nås.

Den första tjänstekonsumenten som ansluter till en tjänsteplattform benäms “ursprunglig tjänstekonsument” och den sista tjänsteproducenten i anropskedjan kallas “faktisk tjänsteproducent”. Mellanliggande tjänsteplattformar är både tjänsteproducenter och tjänstekonsumenter men då i en virtuell form, med virtuell menas att de varken behandlar eller håller den information som hanteras.

Den logiska adressen skickas alltid vidare till nästa part för vidarebefodran, filtrering av svar eller liknade.

Figuren nedan visar hur en tjänstekonsument skickar ett meddelande adresserat till ett källsystem.

1. Tjänstekonsumenten anropar tjänsteplattformen med den tekniska anslutningsadressen ntjp.inera.se och använder källsystemets HSA-id (SE1601) som logisk adress i meddelandet.

2. Tjänsteplattformen översätter med hjälp av TAK den logiska adressen till den tekniska anslutningsadress som gäller för den aktuella tjänsteproducenten (p1.vgr.se).

3. Tjänsteplattformen anropar tjänsteproducenten med den tekniska anslutningsadressen men skickar också med den logiska adressen i meddelandet.

3.1.1 Logisk adressering genom multipla tjänsteplattformar

När meddelanden skickas mellan tjänsteplattformar tar dessa rollen som tjänstekonsument och/eller tjänsteproducent gentemot varandra och övriga tjänstekonsumenter.

Vid logisk adressering genom multipla tjänsteplattformar bibehålls den logiska adressen vid varje länk i förmedlingskedjan, men de tekniska anslutningsadresserna (URL:erna) ändras genom adressuppslag i respektive plattforms TAK.

Exempel: Hur förhåller sig logisk adress till producentens tekniska identitet

I exemplet så representerar den logiska adressen "SE1611" ett källsystem (källsystemsadressering). Det faktiska källsystemets URL är “p1.vgr.se” men i anropskedjan representeras den logiska adressen av ett flertal olika URL:er

I exemplet används SITHS funktionscertifikat både som klient- och servercertifikat för att styrka den tekniska identiteten

Konsument är konfigurerad att rikta alla sina anrop för ett visst tjänstekontrakt till adressen “ntjp.inera.se” och behöver därför inte slå upp adressen till tjänsteproducenten (NTjP) men behöver verifiera att den som man ansluter till via URL:en “ntjp.inera.se” är rätt part och det görs via funktionscertifikatet för “ntjp.inera.se”. Konsumenten använder den logiska adressen “SE1611” i meddelandets kuvertering.

NTjP tar emot anropet och slår upp att anrop till den logiska adressen "SE1611" ska skickas vidare till “rtp.vgr.se”. Ntjp validerar funktionscertifikatet för “rtp.vgr.se”. NTjP har ingen möjlighet att via servercertifikatet säkerställa att “rtp.vgr.se” företräder "SE1611" men förlitar sig på att informationen i NTjPs TAK är korrekt och genomför därför anropet.

RTP tar emot anropet och gör i sin tur ett uppslag av den logiska adressen "SE1611" som pekar på “p1.vgr.se”. RTP validerar serverns funktionscertifikat för att säkerställa att det är rätt system som svarar på anropet.

3.2 Anropsbehörighet

För att stödja hantering av anropsbehörigheter via en eller flera tjänsteplattformar förmedlas ursprunglig tjänstekonsuments identitet i http-headern x-rivta-original-serviceconsumer-hsaid. Om ursprunglig tjänstekonsument dessutom utför anropet å en annan bakomliggande verksamhets vägnar förmedlas verksamhetens identitet i http-headern x-rivta-acting-on-behalf-of-hsaid.

Tjänsteplattformar tar beslut om anropande tjänstekonsument har behörighet att utföra tjänsteanropet.

Detta kan antingen göras explicit eller så kan det delegeras till anropande part baserat på organisationstillit.

Den faktiska tjänsteproducenten kan ta åtkomstbeslut baserat antingen på identiteten för den anropande tjänstekonsumenten, ursprunglig tjänstekonsument, dess uppdragsgivande part eller en kombination av dessa.

Nedanstående bild visar den vanligaste realiseringen av åtkomsthanteringen vid samverkan över flera tjänsteplattformar.

• Åtkomstbeslutet för ursprunglig tjänstekonsument delegeras till första tjänsteplattformen i anropskedjan.

• Efterföljande tjänsteplattformar verifierar endast föregående tjänsteplattforms åtkomstbehörighet.

• Den faktiska tjänsteproducenten verifierar sista tjänsteplattformens åtkomstbehörighet och i vissa fall även ursprunglig konsuments och uppdragsgivande verksamhets åtkomstbehörighet.

• Om åtkomstbehörighet saknas returneras ett felmeddelande. Detta gäller för hela kedjan.

4. Generella regler för en tjänsteplattform

Alla tjänsteplattformar ska tillämpa de regler som beskrivs i detta dokument samt de principer och regler som beskrivs i:

• Referensarkitektur för vård och omsorg - T-boken.

• RIV Tekniska Anvisningar Basic Profile 2.1

En tjänsteplattform behöver i dagsläget stödja RIV-TA Basic Profile version 2.1. För logisk adressering behöver en tjänsteplattform vara bakåtkompatibel mot RIV-TA Basic Profile 2.0, se avsnitt om logisk adressering nedan.

Syftet med detta kapitel är att ge en sammanfattning av de regler från RIV-TA som berör tjänsteplattformar och alla dess ingående komponenter, samt att hänvisa till de dokument där reglerna har sina gällande formuleringar. Regler prefixas med “TP” (tex TP Regel #1).

Observera att komponenter dessutom kan ha kompletterade regler som beskrivs under respektive komponent.

TP Regel #1 Användning av tjänstekontrakt Utgått

TP Regel #2 Transportprotokoll

Tjänstekomponenter skall skicka och ta emot anrop över HTTPS, om inte annat anges i regelverk för specifika tjänstekomponenter.

Motiv: Följsamhet mot RIV Tekniska Anvisningar Basic Profile 2.1

se även RIV Tekniska Anvisningar - Kryptering för ytterligare information.

TP Regel #3 Autentisering

HTTPS-sessioner skall autentiseras med hjälp av HTTPS Mutual Authentication. Det innebär att båda parter autentiserar varandra med hjälp av certifikat.

Tjänstekonsumentens identitet fastställs utifrån attributet SerialNumber i dess certifikat. Certifikat utgivna av SITHS är utformade på detta sätt.

Motiv: Följsamhet mot RIV Tekniska Anvisningar Basic Profile 2.1

TP Regel #4 Bevarande av ursprunglig avsändares identitet i http-header

Efter att autentisering skett enligt ovan, och aktuell förfrågan INTE innehåller http header x-rivta-original-serviceconsumer-hsaid, skall tjänsteplattformen infoga denna http header.

• Tjänstekonsumentens identitet (HSA-ID) skall hämtas från inkommande klientcertifikat

• Identiteten sätta i http-headern i utgående anrop till vilket kan vara till en tjänsteplattform eller den faktiska tjänsteproducenten.

För beskrivning av x-rivta-original-serviceconsumer-hsaid se RIV Tekniska Anvisningar Basic Profile 2.1, Regel #23.

Motiv: Följsamhet mot Detta görs för att nästa komponent i kedjan inte kommer att kunna läsa ursprungsavsändarens certifikat.

Observera: Det är endast betrodda tjänsteplattformar som får sätta denna header. Regel 4,5,6 ska läsas i samverkan

TP Regel #5: Propagering av ursprunglig sändares identitet i http-header

En tjänsteplattform skall propagera ursprunglig avsändares identitet i http-headern ”x-rivta-original-serviceconsumer-hsaid”. Det innebär att om http-headern är satt i ett inkommande anrop så skall tjänsteplattformen föra vidare http-headern i anropet till nästa part i anropskedjan.

Motiv: Detta ger möjlighet att föra vidare information om ursprunglig avsändares identitet även om anropet passerar en eller flera mellanliggande tjänsteplattformar.

TP Regel #6: Säkerställ att anropande tjänsteplattform är betrodd

För att säkerställa en pålitlig propagering av ursprunglig avsändares identitet skall en tjänsteplattform säkerställa att den endast för vidare ursprunglig avsändares identitet från andra tjänsteplattformar som är betrodda. För anrop där denna kontroll misslyckas skall ett felmeddelande skickas tillbaka till avsändaren och felet skall loggas som ett potentiellt försök till intrång.

Motiv: Om inte denna kontroll utförs så riskerar en tjänsteplattform att bli utsatt för angrepp från av avsändare som skickar med en annan tjänstekonsuments identitet (HSA-ID) i http-headern och därmed otillåtet kan uppträda med dess identitet.

TP Regel #7: Vidarebefordran av anropskedja i RIV-header

En tjänsteplattform skall sätta och propagera meddelandets anropskedja i http-headern ”x-rivta-routing-history”. Det innebär att:

• Om http-headern inte är satt i ett inkommande anrop så skall avsändaren betraktas som ursprunglig avsändare och dess identitet (HSA-ID) skall hämtas från inkommande klient certifikat och sättas först i http-headern. Därefter skall tjänsteplattformens eget HSA-id adderas, där tecknet "#" används som avskiljare. Headern skickas i utgående anrop till nästa tjänstekomponent (vilket kan vara den slutgiltiga tjänsteproducenten).

• Om http-headern är satt i ett inkommande anrop så skall tjänsteplattformens eget HSA-id adderas, där tecknet "#" används som avskiljare. Headern skickas i utgående anrop till nästa tjänstekomponent (vilket kan vara den faktiska tjänsteproducenten).

Motiv: Detta ger möjlighet att föra vidare information om den väg ett meddelande tagit mellan ursprunglig tjänstekonsument och slutgiltig tjänsteproducent. Informationen används även för att implementera skydd för rundgång. Den är också viktig vid felsökning.

TP Regel #8: Skydd mot rundgång

Två tjänsteplattformar kan konfigureras i sina respektive tjänsteadresseringskataloger så att de ömsesidigt pekar ut varandra för samma tjänstekontrakt och logiska adress. Risken för detta ökar i och med att mekanismen standardvägval används. Detta skulle leda till rundgång, att de oupphörligen skulle skicka samma meddelande mellan varandra till dess att en eller båda plattformarna slås ut. För att förhindra detta skall en tjänsteplattform implementera skydd mot rundgång.

• En tjänsteplattform skall analysera headern ”x-rivta-routing-history” för alla inkommande meddelanden.

• Om dess egen identitet finns registrerad så innebär det att samma meddelande når plattformen en andra gång, och rundgång har identifierats.

• Vid rundgång skall meddelandet inte skickas vidare. Istället ska felmeddelandet VP014 returneras.

TP Regel #9: Vidarebefordran av http-headers

Utöver reglerna TP Regel #5 och TP Regel #7 så gäller att en tjänsteplattform alltid skall vidarebefodra http-headers vars namn börjar med "x-rivta-". Dessa vidarebefordras oförändrade.

Motiv: Detta ger möjlighet att föra vidare information även om anropet passerar en eller flera mellanliggande tjänsteplattformar.

TP Regel #10 Logisk adressering

Alla tjänstekomponenter skall förutsätta att inkommande meddelanden har en specificerad mottagare i form av en logisk adress. En tjänsteplattform behöver i dagsläget stödja förmedling av anrop utformade enligt RIV TA Basic Profile version 2.0 och 2.1. Det enda skillnad som behöver göras från ett förmedlingsperspektiv är att utläsa den logiska adressen från olika SOAP headers.

• RIV-TA Basic Profile 2.0: {http://www.w3.org/2005/08/addressing }:To

• RIV-TA Basic Profile 2.1: {urn:riv:itintegration:registry:1}:LogicalAddress

Motiv: Följsamhet mot RIV Teknisk Anvisningar Basic Profile 2.0, Regel #8, respektive RIV Tekniska Anvisningar Basic Profile 2.1, Regel #8

TP Regel #11 Exponering av URL:er Utgått

TP Regel #12 Hantering av tekniska fel

I de fall där en tjänstekomponent behöver generera ett felmeddelande som beskriver ett tekniskt fel, skall detta göras med hjälp av SOAP Fault. Detta till skillnad från logiska fel, som ska kommuniceras med vanliga svarsmeddelanden och definieras i respektive tjänstekontraktsbeskrivning.

Motiv: Följsamhet mot RIV Tekniska Anvisningar Basic Profile 2.1, Förtydligad hantering av tekniska fel.

TP Regel #13: Felhantering vid nekad åtkomst från tjänsteproducent

Den virtuella tjänsten ska, när den får ett HTTP 403 Forbidden, omforma detta fel till ett SOAP Fault utformat med felkod VP016 enligt vad som beskrivs i VP Regel #8.

Motiv: Följsamhet mot RIV Tekniska Anvisningar Basic Profile 2.1, Regel #28 Hantering av nekad åtkomst.

TP Regel #14: Tjänsteplattformar ska propagera SOAP fel

En tjänsteplattform som tar emot ett SOAP fel ska propagera detta till nästa aktör i en anropskedja

Motiv: Fel måste hanteras och distribueras på ett enhetligt sätt inom och mellan alla komponenter som omfattas av regelverket RIV-TA.

5. En tjänsteplattforms komponenter

Nedanstående avsnitt beskriver de ingående komponenterna lite mer i detalj och redovisar komponentspecifika regler som kompletterar de som gäller allmänt för tjänsteplattformen.

Endast komponenterna Virtualiseringsplattform och Tjänsteadresseringskatalog är obligatoriska att realisera.

5.1 Tjänsteadresseringskatalog

Tjänsteadresseringskatalogen (TAK) är en stödtjänst som erbjuder administration och åtkomst av information som ligger till grund för den adressering och behörighetskontroll som utförs i en komponenter inom tjänsteplattformen. TAK har till uppgift att:

• Hantera information om vägval genom att översätta logiska adresser till tekniska adresser, i praktiken URL:er.

• Hantera information om konsumenters åtkomstbehörighet.

Den primära konsumenten av informationen i tjänsteadresseringskatalogen är komponenter inom tjänsteplattformen. Konsumtion av TAK inom en tjänsteplattform regleras inte av några nationella tjänstekontrakt. För extern konsumtion finns vissa nationella tjänstekontrakt, se regel #5 nedan.

5.1.1 Anropsbehörighet

Det finns tre olika sätt att sätta upp anropsbehörigheter i TAK: som explicit behörighet, hierarkisk behörighet, eller som standardbehörighet. Explicit behörighet är grunden för behörighet i en tjänsteplattform. Detta kan kompletteras med hierarkisk och standardbehörighet i en viss instans beroende på behov och möjligheter.

Explicit behörighet

En tjänstekonsument ges behörighet att göra ett anrop med ett visst tjänstekontrakt och adressera anropet till en specificerad logisk adressat.

Hierarkisk behörighet

En tjänstekonsument ges behörighet att göra ett anrop med ett visst tjänstekontrakt och adressera anropet till alla adressater under en specificerad nod i HSA organisationsträd som stödjer tjänstekontraktet.

De logiska adresserna ska bestå av ett HSA-id som representerar en verksamhet eller organisation. Genom att tillföra information om de hierarkiska sambanden mellan logiska adresser (exempelvis via en fil över organisationsträdet i HSA) skapas möjligheten att definiera behörighet via en överliggande adress i hierarkin. I de fall där ingen explicit behörighet hittas så hämtas närmast överliggande logiska adress i hierarkin och prövar om den har behörighet definierat. Detta upprepas tills en behörighet hittas eller roten nås.

Roten i organisationshierarkin består definitionsmässigt av den logiska adressen "SE". 

Standardbehörighet

En tjänstekonsument ges behörighet att göra ett anrop med ett visst tjänstekontrakt och adressera anropet till alla adressater som stödjer tjänstekontraktet. Standarbehörighet defineras genom att den logiska adressen "*" ingår i konfigurationen av en åtkomstbehörighet för tjänstekonsument i en tjänsteplattforms tjänsteadresseringskatalog.

Detta kan vara mycket användbart för samverkan där en tjänstekonsument ska nå alla logiska adresser för ett tjänstekontrakt. På detta sätt behövs endast en behörighetstakning istället för hundratals. Ett exempel är att en vårdgivares via dess tjänstekonsument vill kunna skicka elektronisk remiss till andra vårdgivare i Sverige som erbjuder denna tjänst. Ett annat tillämpningsområde kan vara för att ge tjänsteplattformar anropsbehörighet till varandra.

5.1.2 Vägval

Det finns tre olika sätt att sätta upp vägval i TAK: som explicit vägval, hierarkiskt vägval, eller som standardvägval. Explicit vägval är grunden för logisk adressering i en tjänsteplattform. Detta kan kompletteras med hierarkiskt och standardvägval i en viss instans beroende på behov och möjligheter.

Explicit vägval

En tjänsteproducent adresseras med en specificerad logisk adress. Vid en sökning i tjänsteadresseringskatalogen förväntas en exakt matchning av den logiska adressen för att en teknisk anslutningsadress ska returneras.

Hierarkiskt vägval

En tjänsteproducents tekniska anslutningsadress kan logiskt adresseras med verksamhetsadresser under en specificerad nivå i ett verksamhetsträd som nyttjas.

De logiska adresserna ska bestå av ett HSA-id som representerar en verksamhet eller organisation. Genom att tillföra information om det hierarkiska sambanden mellan logiska adresser (exempelvis via en fil över organisationsträdet i HSA) skapas möjligheten att definiera vägval via en överliggande adress i hierarkin. I de fall där inget explicit vägval hittas så hämtas närmast överliggande logiska adress i hierarkin och prövar om den har vägval definierat. Detta upprepas tills ett vägval hittas eller roten nås.

Roten i organisationshierarkin består definitionsmässigt av den logiska adressen "SE". 

Standardvägval

En tjänsteproducents tekniska anslutningsadress kan logiskt adresseras med vilken logisk adress som helst. Alla logiska adressater kommer matchas mot samma vägval. I TAK representeras ett standardvägval av att den logiska adressaten registreras som en asterisk (“*”).

Exempel på tillämpning är att en regional tjänsteplattform kan definiera ett standardvägval till den nationella tjänsteplattformen för att inte behöva registrera samtliga logiska adresser som finns i den nationella TAKen. Detta blir särskilt tillämpligt för sådana adresser där den nationella plattformen använder hierarkiskt vägval men där den regionala plattformen inte gör det.

Exempel: Hur kan olika vägvalsmekanismer kombineras i en anropskedja

• RPT1 använder standardvägval till “ntjp.inera.se” (NTJP) om det inte finns något explicit vägval konfigurerat för den angivna logiska adressen

  • Eftersom ”SE161123” inte finns konfigurerat så skickas anropet till “ntjp.inera.se” (NTJP)

• NTJP använder hierarkiskt vägval om det inte finns explicita vägval konfigurerade för den angivna logiska adressen

  • Eftersom “SE161123” inte finns konfigurerat så söker NTJP i HSA trädet

  • “SE161123” hittas och ligger under “SE1601”

  • Eftersom “SE1601” har explicit vägval så skickas anropet till “rpt.vgr.se” (RPT2)

• RTP2 använder enbart explicita vägval

  • Eftersom “SE161123” finns konfigurerat så skickas anropet till producenten “p1.vgr.se”

TAK Regel #1: Lagring av vägvalsinformation

Tjänsteadresseringskatalogen skall lagra vägvalsinformation. Denna information består av följande delar:

• Tjänstekontrakt inklusive tjänstedomän, i formatet URN, plus kontraktets major-version. Exempel: urn:riv:clinicalprocess:activityprescription:prescribe:ChangePrescription:1

• Logisk adress till en organisationsenhet eller ett IT-system

• Version av RIV-TA i kortformat, t.ex. ”rivtabp21”

• Associerad teknisk adress, i form av en http URL.

TAK Regel #2: Exponering av vägvalsinformation

Tjänsteadresseringskatalogen skall exponera sin registrerade vägvalsinformation till tjänsteplattformens komponenter över valfritt gränssnitt.

TAK Regel #3: Lagring av anropsbehörigheter

Tjänsteadresseringskatalogen skall kunna lagra anropsbehörigheter. Dessa anropsbehörigheter består av följande delar:

• Tjänstekontrakt inklusive tjänstedomän, i formatet URN, plus kontraktets major-version. Exempel: urn:riv:clinicalprocess:activityprescription:prescribe:ChangePrescription:1

• logisk adress

• tjänstekonsumentens identitet

TAK Regel #4: Exponering av anropsbehörigheter

Tjänsteadresseringskatalogen skall exponera sina registrerade anropsbehörigheter till tjänsteplattformens komponenter över valfritt gränssnitt.

TAK Regel #5: Tjänstekontrakt

Tjänsteadresseringskatalogen ska implementera den nationella tjänstedomänen infrastructure:itintegration:registry för att stödja externa tjänstekonsumenter. Se http://rivta.se/domains/infrastructure_itintegration_registry.html.

5.2 Engagemangsindex

Om en tjänsteplattform har en aggregeringsplattform kan även engagemangsindex behöva implementeras. Här beskrivs engagemangsindexets funktion övergripande och de regler som engagemangsindex behöver uppfylla.

Engagemangsindex är en stödtjänst där det finns information om vilka källsystem som har information om en invånare/patient. Engagemangsindex har till uppgift att avlasta aggregerande tjänster genom att peka ut vilka tjänsteproducenter som har uppgifter av den typ som den specifika tjänsten hanterar. Med hjälp av denna information behöver tjänsten enbart kontakta dessa tjänsteproducenter för att kunna leverera ett fullständigt resultat.

Engagemangsindex är utförligt beskrivet i T-boken (Referensarkitektur för vård och omsorg - T-boken) samt i tjänstekontraktsbeskrivningen för domänen: engagemangsindex - itintegration:engagementindex.

Engagemangsindex har även en tjänstedomän som innehåller de tjänstekontrakt som används för att hantera informationen. För detaljer se aktuell Tjänstekontraktsbeskrivning för EI i domänen engagemangsindex - itintegration:engagementindex.

Engagemangsindex producerar tre tjänster

• Update används av informationsbärande system för att uppdatera information i indexet

• FindContent används av aggregerande tjänster för att söka efter information i indexet

• ProcessNotification används för att synkronisera information mellan index. ett index kan vara producent eller konsument eller både och beroende på synkroniseringmönster

EI Regel #1: Datakommunikation

Engagemangsindex skall stödja alla kommunikationsregler i de RIV TA-profiler som tjänstedomänen itintegration:engagementindex tillämpar.

EI Regel #2: Tjänstedomän

Tjänsten ska implementera tjänstedomänen itintegration:engagementindex. Det innefattar bland annat:

• Datamodell för att lagra engagemangsdata.

• Stöd för att replikera engagemangsdata med andra engagemangsindex, i enlighet med tjänstekontraktsbeskrivningen.

• Tjänst för att exponera en persons vårdengagemang mot aggregeringsplattformen.

Se tjänstekontraktsbeskrivning för engagemangsindex för komplett information.

5.3 Virtualiseringsplattform

Virtualiseringsplattformen uppfyller T-bokens arkitekturella princip om lös koppling mellan tjänstekonsumenter och -producenter. Den logiska adressen pekar ut en tjänsteproducents URL via information i TAK. På detta sätt döljs systems tekniska anslutningsadress från tjänstekonsumenten. En verksamhet kan därmed förändra sin systemstruktur utan att behöva påverka logiska adresser och därmed tjänstekonsumenter. Det enda som behöver uppdateras är informationen om anslutningsadress i TAK.

Virtuella tjänster agerar som en ställföreträdare för alla tjänsteproducenter som implementerat ett tjänstekontrakt och anslutit till aktuell tjänsteplattform. Den uppträder som en tjänsteproducent men vidarebefordrar endast frågan till den faktiska producenten som den logiska adressen representerar och returnerar svaret till tjänstekonsumenten.

En virtuell tjänst består översiktligt av två funktionsblock

• En tjänsteproducent baserad på samma tjänstekontrakt som den virtuella tjänsten

• En tjänstekonsument som anropar producenten. tjänstekonsumenten tar hjälp av tjänsteadresseringskatalogen (TAK) för att:

  • Validera att aktuell tjänstekonsument har rätt att anropa den den logiska adressaten med det tjänstekontraktet.

  • Erhålla den tekniska adressen (URL) till mottagande tjänsteproducent.

VP Regel #1: Datakommunikation

Virtualiseringsplattformen skall följa alla kommunikationsregler i aktuella RIV-profiler.

VP Regel #2: Åtkomstkontroll

Virtualiseringsplattformen skall ha möjlighet att vid inkommande anrop kontrollera åtkomstbehörigheten för kombinationen av följande:

• Anslutande tjänstekonsument.

• Meddelandets logiska mottagaradress

• Anropat tjänstekontrakt

Åtkomstbesluten skall baseras på information som lagras i tjänsteadresseringskatalogen. Om åtkomst inte tillåts skall den inkommande förfrågan inte vidarebefordras. Istället skall ett felmeddelande returneras, enligt aktuell RIV-profil.

Behörighet kan kontrolleras mot TAK enligt nedanstående metoder:

(Observera att metod 2 och 3 är valfria)

1. Explicit behörighet

2. Hierarkisk behörighet

3. Standardbehörighet

Om varken 1, 2 eller 3 identifierar en behörighet så returneras ett VP007-fel till tjänstekonsumenten.

VP Regel #3: Generera tjänst med utgångspunkt från WSDL Utgått

VP Regel #4: Vägval för anrop

För att kunna vidarebefordra inkommande meddelanden till rätt tjänsteproducent, behöver virtualiseringsplattformen kunna slå upp den tekniska adress som meddelandet ska vidarebefordras till. Denna information tas fram ur den information som är registrerad i tjänsteadresseringskatalogen, eller via andra metoder, baserat på:

• Meddelandets logiska mottagaradress

• Anropat tjänstekontrakt, inklusive tjänstedomän och kontraktets huvudversion

• Anropad RIV-profil

Uppslag av vägval kan göras enligt nedanstående metoder och prioritet:

(Observera att metod 2 och 3 är valfria)

1. Explicit vägval

2. Hierarkiskt vägval

3. Standardvägval

Om varken 1, 2 eller 3 identifierar ett vägval så returneras ett VP004-fel till konsumenten.

VP Regel #5: Vidarebefordran av anrop

Virtualiseringsplattformen skall, såvida autentisering, åtkomstkontroll, vägval och övrig validering lyckats, skicka tjänstekonsumentens meddelande vidare till tjänsteproducenten. Svarsmeddelandet från tjänsteproducenten, oavsett om det är ett ordinarie svar eller ett felmeddelande, skall därefter returneras till tjänstekonsumenten. Se också TP regel #14

VP Regel #6: Översättning mellan RIV-TA versioner Utgått

VP Regel #7 Tjänsteinteraktioner Utgått

VP Regel #8: Felkoder

Virtualiseringsplattformen skall returnera felmeddelanden enligt respektive RIV TA-profil som HTTP 500 med SOAP Fault, med felkoder och felsträng enligt tabellen nedan. SOAP Fault-elementet detail används för att inkludera ytterligare felinformation så som spårningsinformation eller ytterligare detaljer kring det inträffade felet. Se också TP regel #14

• Terminologi från SOAP 1.1

Texten [namn tjänsteplattform] ska vara en textuell beskrivning av den tjänsteplattformsinstans (t.ex. ‘NTJP-PROD’ eller ‘SLL-QA’) där felet upptäcktes. Dessa namn ägs av vardera tjänsteplattforms ansvariga förvaltningsorganisation som måste tillse att namnen är unika.

VP Regel #9: Propagering av ursprunglig sändares identitet i http header

Flyttad till TP Regel #5

VP Regel #10: Säkerställ att anropande tjänsteplattform är känd

Flyttad till TP Regel #6

VP Regel #11: Vidarebefordran av anropskedja i RIV-header

Flyttad till TP Regel #7

Regel #12: Skydd mot rundgång

Flyttad till TP Regel #8

Regel #13: Vidarebefordran av RIV-headrar

Flyttad till TP Regel #9

5.4 Aggregeringsplattform

Aggregeringsplattformen exponerar aggregerande tjänster baserade på RIV TA tjänstekontrakt.

En aggregerande tjänst är en integrationstjänst som baserat på information i Engagemangsindex sammanställer information, oftast för en viss person. Informationstypen styrs av det tjänstekontrakt som den aggregerande tjänsten baseras på. Villkoret för att kunna använda ett tjänstekontrakt i en aggregerande tjänst är att kontraktets svarsmeddelande är utformat så att svaret kan vara en lista och därigenom stöder att flera svar sammanfogas.

Principerna för aggregerande tjänster är beskrivet i T-boken. För information om realisering av en aggregerande tjänst på en specifik tjänsteplattform hänvisas till respektive tjänsteplattformsförvaltning.

En aggregerande tjänst består översiktligt av fyra funktionsblock

• en tjänsteproducent baserad på samma tjänstekontrakt som den virtuella tjänsten

• en aggregeringsfunktion som slå ihop svar från samtliga producenter till en lista

• en funktion för informationslokalisering som identiferar vilka producenter som bär information av den aktuella typen. Ofta använder denna funktion stödfunktionen engagemangsindex.

• En tjänstekonsument som kontrollerar om konsumenten har behörighet att anropa de identifierade producenterna samt slår upp teknisk anslutningsadress för dessa.

5.4.1 Logisk adressering av aggregerande tjänst

Även aggregerande tjänster adresseras via logiska adresser. Ur tjänstekonsumentens perspektiv uppträder en aggregerande tjänst som en tjänsteproducent. Den exekverar på komponenten Aggregeringsplattform inom ramen för en tjänsteplattform. Principerna för aggregerande tjänster beskriv i T-boken (Referensarkitektur för vård och omsorg - T-boken).

Hur den logiska adressen för en aggregerande tjänst utformas bestäms av den organisation som tillhandahåller den.

• En aggregerande tjänst som finns på den nationella tjänsteplattformen adresseras primärt med Ineras organisationsidentifierare som logisk adress.

  • Om det skulle finnas flera aggregerande tjänster för samma tjänstekontrakt så adresseras dessa med organisationsidentifieraren +lämpligt suffix.

• För regionala/lokala aggregerande tjänster hanteras adresseringen enligt lokala beslut.

Observera att i figuren ovan framgår att den logiska adressen 556559-4230, som finns i anropet till nationella tjänsteplattformen, enbart pekar ut den aggregerande tjänsten. Den aggregerande tjänsten kommer dock i sin tur att anropa respektive tjänsteproducent baserat på de logiska adresser som finns i EI-posterna (inringade med röd streckad linje i bilden ovan). Precis som i fallet med en virtuell tjänst så översätts de logiska adresserna till URL:er genom uppslag mot TAK.

5.4.2 Relationer till andra tjänster

Virtualiseringsplattform

En aggregerande tjänst exponerar samma tjänstekontrakt som motsvarande virtuella tjänst. Tjänsteplattformen ska utifrån en och samma URL kunna styra vilken komponent i tjänsteplattformen som hanterar anropet: en virtuell tjänst, en aggregerande tjänst eller en anpassningstjänst beroende på den logiska adressen i kuverteringen.

Tjänsteadresseringskatalog

Varje aggregerande tjänst i aggregeringsplattformen uppträder som en tjänsteproducent, och behöver således registreras i tjänsteadresseringskatalogen (TAK).

Detta gör att aggregerande tjänster kan anropas via virtualiseringsplattformen, förutsatt att tjänstekonsumenter anger rätt logisk mottagaradress.

Engagemangsindex

Enligt mönstret i T-boken använder sig aggregeringsplattformen av engagemangsindex för att få information om vilka tjänsteproducenter som innehåller information som behövs i aggregeringen. Detta leder till att aggregeringsplattformen även behöver tillgång till den lokala instansen av engagemangsindex.

AgP Regel #1 Datakommunikation

Aggregeringsplattformen skall följa alla kommunikationsregler i RIV-TA.

AgP Regel #2 Generera tjänst med utgångspunkt från WSDL-filer

Godkända tjänstekontrakt levereras i formaten WSDL och XSD, enligt RIV-TA Basic Profile 2.1. Utifrån dessa artefakter skall en aggregerande tjänst kunna skapas och installeras i aggregeringsplattformen.

Källa: RIV Tekniska Anvisningar - Basic Profile 2.1 Regel #18

AgP Regel #3 Utgående anrop till tjänsteproducenter

Aggregeringsplattformen skall vidarebefordra den inkommande förfrågan till de tjänsteproducenter som enligt tjänsten engagemangsindex innehåller information för att kunna sammanställa ett komplett svar.

I de utgående frågemeddelandena ändras den logiska mottagaradressen till respektive tjänsteproducents logiska adress. Den ursprungliga tjänstekonsumentens identitet vidarebefordras med hjälp av http header x-rivta-original-serviceconsumer-hsaid, se kapitel 4.

AgP Regel #4 Sammanställning av information

Aggregeringsplattformen skall sammanställa de svar som tas emot från enskilda tjänsteproducenter och skapa ett aggregerat svar. Detta svar skall sedan returneras till den ursprungliga tjänstekonsumenten.

Eventuella felmeddelanden från tjänsteproducenter skall inte infogas i det sammanställda svaret.

AgP Regel #5 ProcessingStatus i svar till konsument

En aggregerande tjänst skall infoga en header, enligt aktuell RIV TA-profil, i sitt svar till en tjänstekonsument. Headern har namnet ProcessingStatus och innehåller en lista över de tjänsteproducenter som bidragit till svaret, samt uppgift om huruvida respektive delsvar kommer direkt från källsystemets primärdatabas eller från en cache.

I förekommande fall innehåller headern även information om tjänsteproducenter som svarat med felmeddelande, eller inte svarat alls.

För mer information, se RIV Tekniska Anvisningar - Basic Profile 2.1 med status för anrop till aggregerande tjänster 2.1: Regel #2.

AgP Regel #6 Filtrering av ej åtkomliga och ej kompatibla källsystem

Engagemangsindex tillhandahåller information om vilka källsystem som innehåller information av ett specifikt slag om en specifik person. Information från alla dessa källsystem är dock ibland inte möjliga att aggregera av följande skäl:

• Den aktuella tjänstekonsumenten har inte anropsbehörighet till alla dessa källsystems logiska adresser.

• Vissa källsystem stöder inte den aktuella huvudversionen av tjänstekontraktet.

Innan utgående anrop initieras skall Aggregeringsplattformen via Tjänsteadresseringskatalogen undersöka tjänstekonsumentens anropsbehörighet till källsystemen, samt källsystemens stöd för den aktuella huvudversionen av tjänstekontraktet. Källsystem som inte uppfyller dessa villkor skall inte anropas. Detta för att undvika att överflödiga felmeddelanden genereras i de olika plattformskomponenterna.

Då detta utelämnande inte beror på något tekniskt fel, skall Aggregeringsplattformen inte returnera information om utelämnade källsystem i ProcessingStatus (se Regel #5).

5.5 Anpassningsplattform

Anpassningsplattformen kan realisera funktionera av typen tjänsteväxel och anpassningstjänst som är benämningar på två olika koncept som används för att översätta kommunikation till och från RIV-TA.

5.5.1 Tjänsteväxel

En tjänsteväxel används för att översätta mellan den modell för teknisk kommunikation som används inom hälso- och sjukvårdssektorn och modeller som tillämpas av externa parter, såsom myndigheter. Ett exempel är översättning mellan RIV Tekniska Anvisningar och myndigheters SHS-arkitektur.

Tjänsteväxeln utför en generisk protokollväxling, vilket innebär att den kan översätta aspekter som t.ex. protokoll, adressering och säkerhetsmekanismer, för att matcha en specifik, extern arkitektur. Däremot förändrar tjänsteväxeln vanligtvis inte meddelandeinnehåll. Därför behöver tjänsteväxeln inte känna till specifika tjänstekontrakt, utan kan ha en gemensam ändpunkt för all kommunikation.

Den ändpunkt som tar emot RIV-TA-meddelanden för vidarebefordran till en extern part kallas partnerutgång och agerar tjänsteproducent för den aktuella externa samverkansarkitekturen. Motsatsen kallas partneringång och agerar som en tjänstekonsument.

Den gemensamma arkitekturen utgår från att all tjänsteväxling sker i den nationella tjänsteplattformen, och att en varje extern samverkansarkitektur som hälso- och sjukvårdssektorn behöver kommunicera med har en separat tjänsteväxel.

För mer information se Referensarkitektur för vård och omsorg - T-boken kapitel 5.2 och 5.3.

5.5.2 Anpassningstjänst

Anpassningstjänster används för att anpassa IT-system inom hälso- och sjukvårdssektorn till RIV TA-standarden. En anpassningstjänst konstrueras vanligtvis för ett specifikt, icke RIV-kompatibelt, IT-system och anpassar in- och utgående anrop mellan RIV-TA och systemet. Detta kan innebära att såväl protokoll, adressering, säkerhetsmekanismer och meddelandeinnehåll förändras.

En anpassningstjänst är en valfri komponent som främst används inom regionala tjänsteplattformar. Anpassningstjänster i en tjänsteplattform bör endast användas om leverantören för det aktuella IT-systemet inte kan tillhandahålla en RIV TA-kompatibel anslutningspunkt inom ramen för sitt förvaltningsobjekt.

5.5.3 Jämförelse

Både tjänsteväxel och anpassningstjänst används för att översätta kommunikation, men har olika syfte och omfattning:

• En tjänsteväxel används för att översätta valfria tjänstekontrakt mellan RIV-TA och en specifik extern meddelandearkitektur.

• En anpassningstjänst används för att översätta specifika tjänstekontrakt mellan RIV-TA och ett specifikt IT-system.

Följande illustration och tabell visar skillnader och likheter mellan tjänsteväxel och anpassningstjänster.