Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

RIV Tekniska Anvisningar Basic Profile Valfria tillägg


Version 1.1

ARK_0028

2014-09-08

Table of Contents




Utgåvehistorik

Utgåva

Revision Datum

Beskrivning

Ändringarna gjorda av

Definitiv revision fastställd av

PA1

2013-11-05

Första utgåva av anvisningar för valfria tillägg till RIV-TA v2.1.


Innehåller:

  1. Anvisning för att ange ursprunglig avsändare
  2. Anvisning för att ange status på bearbetning i aggregerande tjänst

magnus.larsson@inera.se



A

2013-11-13

Uppdaterade mall och några typos

Lars Erik Röjerås


1.1

2014-09-08

Uppdaterat till Inera mall

Lennart Eriksson

1          Översikt

Detta dokument beskriver anvisningar för valfria tillägg till regelverket för RIV Tekniska Anvisningar Basic Profile 2.1. Anvisningarna är generellt sett valfria men kan för vissa typer av komponenter, t ex tjänsteplattformar, vara obligatoriska. Enskilda domäner kan också ta beslut om att göra vissa valfria tillägg obligatoriska inom sin domän, se respektive domäns Tjänstekontraktsbeskrivning.

Image Removed 

Dokumentet beskriver följande anvisningar:

  • RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1
  • RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1

1.1          Tillgänglighet

Detta dokument är publicerade 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 Landsting) anges (men inte på ett sätt som antyder att de godkänt eller rekommenderar din användning av verket).

Denna profil är verifierad genom exempelapplikationer. Källkoden [R11] för dessa distribueras under öppen-källkodslicensen Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

1.2         Referenser

...

Ref

...

Dokument

...

Beskrivning och ev. webbadress

...

Ansvarig

...

[R1]          

...

T-Boken

...

T-boken. Styrande tekniska principer och teknisk referensarkitektur för den nationella arkitekturen:

Webblänk till PDF för REV B:

http://rivta.se/documents/ARK_0019  

...

Arkitektur och regelverk, Center för eHälsa i samverkan

...

[R2]          

...

Översikt RIV Tekniska Anvisningar REV D

...

Bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av denna anvisning.

Webblänk till PDF för översikten:

http://rivta.se/documents/ARK_0001  

...

Arkitektur och regelverk, Center för eHälsa i samverkan

...

[R3]          

...

RIV Teknisk Anvisning - Basic Profile 2.1

...

Anvisningen innehåller regeluppsättningen som definierar profilen.

Webblänk till PDF för anvisningen:

 http://rivta.se/documents/ARK_0002  

...

Arkitektur och regelverk, Center för eHälsa i samverkan

...

[R4]          

...

RIV Teknisk Anvisning Tjänsteschema 2.1

...

Anvisning för att specificera ett XML-schema (tjänsteschema) för ett tjänstekontrakt. Definierar elementen för WSDL-filens meddelanden.

Webblänk till PDF för anvisningen:

http://rivta.se/documents/ARK_0005  

...

Arkitektur och regelverk, Center för eHälsa i samverkan

...

[R5]          

...

WS-I Basic Profile

...

”Defines the WS-I Basic Profile 1.1, consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability ”

Weblänk till WS-I Basic Profile: http://www.ws-i.org/Profiles/BasicProfile-1.1.html

...

The Web Services Interoperability Organization och ISO

...

[R6]          

...

WS-I Simple Soap Binding Profile

...

“Defines the WS-I Simple SOAP Binding Profile 1.0, consisting of a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications which promote interoperability”

Weblänk till profilen : http://www.ws-i.org/Profiles/SimpleSoapBindingProfile-1.0.html

...

The Web Services Interoperability Organization

...

[R7]          

...

HCC spec.

...

SITHS HCC: Certifikat för svensk vård och omsorg.

Webblänk till PDF för REV 2.35: http://www.inera.se/TJANSTER--PROJEKT/SITHS/

...

Inera AB

...

[R8]          

...

SOAP 1.1 spec

...

Definierar ett XML-baserat protokoll för utbyte av information. Är grunden för den standardisering som går under benämningen ”web services”.

Webblänk till specifikationens hemsida:  http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

...

W3C

...

[R9]          

...

WSDL 1.1 spec

...

Beskrivningsspråk för web-services. Syftar till att stödja utvecklingsverktyg i design-time och web-service-konsumenter i run-time.

Webbänk till specifikationens hemsida:  http://www.w3.org/TR/wsdl

...

W3C

...

[R10]        

...

Exempel - Tjänsteinteraktion

...

Alla fragment av WSDL och XML-scheman som finns i detta dokument härrör ur den tjänsteinteraktion som ligger till grund för exempelapplikationerna för Java och .Net.

Mer information återfinns i wikin:

http://rivta.se/wiki

...

Arkitektur och regelverk, Center för eHälsa i samverkan

...

[R11]        

...

Exempel – konsument och producent i Java och .Net

...

Referensapplikationerna syftar till att vara ett generellt underlag för den utvecklare som ska utveckla en tjänstekonsument eller en tjänsteproducent för en tjänsteinteraktion som följer denna profil. Det är en målsättning att detta ska avlasta nationella projekt från att ta fram projektspecifika kodexempel för varje nationell tjänsteinteraktion som specificeras enligt denna profil.

Mer information återfinns i wikin:

http://rivta.se/wiki

...

Arkitektur och regelverk, Center för eHälsa i samverkan

2         RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1

2.1         Inledning

Denna anvisning är en påbyggnad på Basic Profile 2.1 för att möjliggöra överföring av information om den ursprungliga avsändarens (tjänstekonsuments) identitet. Överföringen skall ske via en http header med namnet ”x-rivta-original-serviceconsumer-hsaid". Anvisningen är obligatorisk för tjänsteplattformar men frivillig för tjänsteproducenter. Anvisningen påverkar inte tjänstekonsumenter.

Anvisningen innehåller endast regeluppsättningen som definierar profilens avvikelser från ”Basic Profile”. För bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av profilen hänvisas till Översikt RIV Tekniska Anvisningar 2.1 [R2].

2.1.1         Målgrupp

Denna anvisning riktar sig dels till leverantörer som implementerar tjänsteplattformar enligt T-boken [R1] och till implementationer av tjänsteproducenter som vill veta identiteten på den ursprungliga tjänstekonsumenten i de fall anropet passerat en eller flera tjänsteplattformar på vägen till tjänsteproducenten.

2.1.2        Syfte

Syftet med denna anvisning är att beskriva en utökning av basprofilen som ger möjlighet att föra över information om den ursprungliga avsändarens (tjänstekonsuments) identitet till en tjänsteproducent. En tjänsteproducent kan använda denna information till exempel för loggning eller behörighetsmekanismer.

I de fall tjänstekonsument och tjänsteproducent kommunicerar utan mellanliggande tjänsteplattform behövs inte denna http header då tjänsteproducenten i det fallet kan hämta avsändarens identitet direkt från tjänstekonsumentens klient certifikat, se regel #6 i RIV TA Basic Profile 2.1 [R3]. Detta illustreras av följande bild:

Image Removed

I de fall tjänstekonsument och tjänsteproducent kommunicerar via en eller flera mellanliggande tjänsteplattformar har samtliga tjänsteplattformar till ansvar att sätta denna http header om den inte redan är satt av en tjänsteplattform tidigare i anropskedjan. Är http header redan satt ansvarar respektive tjänsteplattform för att föra http headern vidare i anropet till tjänsteproducenten alternativt till nästa tjänsteplattform.

Följande bild visar hur ursprungsidentiteten förs via den nationella tjänsteplattformen från anropande tjänstekonsuments klient certifikat till tjänsteproducenten via http headern:

Image Removed

Nedan ett mer komplext exempel med tre tjänsteplattformar inblandade i anropet, dels en applikationslokal tjänsteplattform (också känd som Applikation Service Bus, ASB), dels en regional samt den nationella tjänsteplattformen. I detta exempel så är det den applikationslokala tjänsteplattformen som fångar upp identiteten från tjänstekonsumentens klient certifikat och sätter det i http headern. Den regionala och den nationella tjänsteplattormen för bara vidare inkommande http header till sitt utgående anrop:

Image Removed

Till sist ett exempel där vi vänder på anropskedjan för att visa hur det ser ut med en tjänsteproducent som sitter bakom en applikationslokal tjänsteplattform som i sin tur anropas av en regional tjänsteplattform. Tjänstekonsumenten i detta exempel anropar den nationella tjänsteplattformen som i sin tur anropar den regionala. Det blir nu den nationella tjänste-plattformen som fångar upp identiteten från tjänstekonsumentens klient certifikat och sätter det i http headern. Den regionala och den applikationslokala tjänsteplattormen för bara vidare inkommande http header till sitt utgående anrop:

Image Removed

2.2        Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1” och refereras ${profil}

Denna profils kortnamn är ”rivtabpos21” och refereras ${profilKortnamn}

2.3        Följsamhet mot externa regelverk

Här definieras de externa regelverk (t.ex. profiler) som utgör regelbas för denna profil. Det är en målsättning att denna profil ska kunna läsas uppifrån och ner utan detaljerad kunskap om externa regelverk. För regler som inte lyfts fram i denna profil (av förbiseende eller för att de inte bedömts viktiga) hänvisas till de externa regelverk som redovisas här.

Regel #1, Följsamhet mot RIV TA BP 2.1

Utformning av WSDL skall följa RIV TA BP 2.1, med tillägg av de regler som definieras i denna profil.

Motiv: Interoperabilitet

2.4        Detaljerade regler

Regel #2: 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:

  1. 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 i http headern i utgående anrop till tjänsteproducenten alternativt till nästa tjänsteplattform.
  2. Om http headern är satt i ett inkommande anrop så skall tjänsteplattformen föra vidare http headern i anropet till tjänsteproducenten alternativt till nästa tjänsteplattform.

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

Regel #3: Mottagande av ursprunglig sändares identitet i http header

En tjänsteproducent kan utnyttja http headern ”x-rivta-original-serviceconsumer-hsaid” för att få redan på identiteten av den ursprungliga avsändaren om anropet kommer från en eller flera mellanliggande tjänsteplattformar.

Motiv: Detta ger en valfri möjlighet för tjänsteproducenter att identifiera den ursprungliga avsändaren.

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

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 den litar på, t ex genom att upprätthålla en lista på IP adresser eller HSA-ID för de tjänsteplattformar den litar på och som den kontrollerar mot innan den accepterar en inkommande http header för ursprunglig avsändare. För anrop där denna kontroll misslyckas skall ett felmeddelanden 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.

3         RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1

3.1         Inledning

Denna anvisning är en påbyggnad på Basic Profile 2.1 för att möjliggöra rapportering av teknisk information om bearbetningen i en aggregerande tjänst. Informationen skickas tillbaka till anropande tjänstekonsument i SOAP svaret som en SOAP header med namnet "ProcessingStatus".

3.1.1         Målgrupp

Denna anvisning riktar sig till dem som ska implementera aggregerande tjänster samt till tjänstekonsumenter som är intresserade av att ta del av teknisk information om bearbetningen i en aggregerande tjänst.

Notera att utformning av WSDL för en nationell tjänsteinteraktion i enlighet med RIV TA inte påverkas av denna anvisning, för detaljer se nedan.

3.1.2        Syfte

Syftet med denna anvisning är att beskriva en utökning av basprofilen som ger möjlighet att rapportera teknisk information om bearbetningen i en aggregerande tjänst. Informationen skickas tillbaka till anropande tjänstekonsument i SOAP svaret som en SOAP header med namnet "ProcessingStatus".

SOAP headern innehåller en lista med en rad per anropat källsystem och ger per källsystem information huruvida anropet gick bra, om svaret kom direkt från cache eller om det hämtades från källsystemet, hur gammal den cachade informationen är. För detaljer se schemafilen interoperability_headers_1.0 i psuedodomänen interoperability:headers i källkodsträdet på http://rivta.se

Följande dokumentation är hämtad från XML Schemat ovan:

Image Removed

SOAP headern beskrivs inte i de tjänsteinteraktioner (WSDL-filer) som en aggregerande tjänst följer, detta för att kunna använda samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder.

Nedan ett exempel där en tjänstekonsument anropar en aggregerande tjänst som via engagemangsindex får reda på att det finns information att hämta i två olika källsystem. Den aggregerande tjänsten anropar de två källsystemen (parallellt) och sätter samman ett aggregerat svar till tjänstekonsumenten där SOAP header ”ProcessingStatus” ingår. Detta illustreras av följande bild:

Image Removed

Givet att båda källsystemen svarar korrekt så kommer ProcessingStatus – SOAP headern se ut något i stil med följande:

Code Block
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ProcessingStatus xmlns="urn:riv:interoperability:headers:1">
         <ProcessingStatusList>
            <logicalAddress>HSA-ID-A</logicalAddress>
            <statusCode>DataFromSource</statusCode>
            <isResponseFromCache>false</isResponseFromCache>
            <isResponseInSynch>true</isResponseInSynch>
            <lastSuccessfulSynch>20130904124333</lastSuccessfulSynch>
         </ProcessingStatusList>
         <ProcessingStatusList>
            <logicalAddress>HSA-ID-B</logicalAddress>
            <statusCode>DataFromSource</statusCode>
            <isResponseFromCache>false</isResponseFromCache>
            <isResponseInSynch>true</isResponseInSynch>
            <lastSuccessfulSynch>20130904124333</lastSuccessfulSynch>
         </ProcessingStatusList>
      </ProcessingStatus>
   </soapenv:Header>

Om däremot något av de anropade källsystemen inte svarar inom en föreskriven tid eller returnerar ett fel så kommer ProcessingStatus-SOAP headern innehålla information om att svaret inte är komplett utan bara partiellt samt information om vilket fel som uppstod. I bilden nedan illustreras ett exempel där tre källsystem anropas men bara två ger svar, det tredje orsakar en timeout (dvs svarar inte inom föreskriven maxtid):

Image Removed

SOAP-headern ProcessingStatus kommer då se ut något i stil med följande:

Code Block
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
    <ProcessingStatus xmlns="urn:riv:interoperability:headers:1">
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-A</logicalAddress>
        <statusCode>DataFromSource</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>true</isResponseInSynch>
        <lastSuccessfulSynch>20130905111504</lastSuccessfulSynch>
      </ProcessingStatusList>
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-B</logicalAddress>
        <statusCode>DataFromSource</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>true</isResponseInSynch>
        <lastSuccessfulSynch>20130905111504</lastSuccessfulSynch>
      </ProcessingStatusList>
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-C</logicalAddress>
        <statusCode>NoDataSynchFailed</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>false</isResponseInSynch>
        <lastUnsuccessfulSynch>20130905111504</lastUnsuccessfulSynch>
        <lastUnsuccessfulSynchError>
          <causingAgent>virtualization_platform</causingAgent>
          <code>43000</code>
          <text>Read timed out. Failed to route event via endpoint:
            org.mule.module.cxf.CxfOutboundMessageProcessor. Message payload is
            of type: PostMethod, Read timed out</text>
        </lastUnsuccessfulSynchError>
      </ProcessingStatusList>
    </ProcessingStatus>
  </soapenv:Header>

3.2        Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1” och refereras ${profil}

Denna profils kortnamn är ”rivtabpagg21” och refereras ${profilKortnamn}

3.3        Följsamhet mot externa regelverk

Här definieras de externa regelverk (t.ex. profiler) som utgör regelbas för denna profil. Det är en målsättning att denna profil ska kunna läsas uppifrån och ner utan detaljerad kunskap om externa regelverk. För regler som inte lyfts fram i denna profil (av förbiseende eller för att de inte bedömts viktiga) hänvisas till de externa regelverk som redovisas här.

Regel #1, Följsamhet mot RIV TA BP 2.1

Utformning av WSDL skall följa RIV TA BP 2.1, med tillägg av de regler som definieras i denna profil.

Motiv: Interoperabilitet

3.4        Detaljerade regler

Regel #2: Aggregerande tjänster skall returnera status om bearbetning av ett anrop

Implementationer av aggregerande tjänster skall returnera en SOAP header med namnet "ProcessingStatus". Headern skall rapportera teknisk information om bearbetningen i tjänsten. Headern skall följa elementet ProcessingStatus i XML Schemat: interoperability_headers_1.0.xsd.

Motiv: Ge tjänstekonsumenter möjligheten att verifiera att de fått ett komplett svar från den aggregerande tjänsten och om så inte är fallet kunna rapportera tillbaka till användaren att svaret bara är partiellt.

Exempel: Se ovan i kapitlet Syfte.

Regel #3: Tjänstekonsumenter av en aggregerande tjänster kan ta del av status om bearbetning av ett anrop

Tjänstekonsumenter av en aggregerande tjänster kan ta del av status om bearbetning av ett anrop till en aggregerande tjänst genom att ta del av innehållet i SOAP headern med namnet "ProcessingStatus" i svaret från den aggregerande tjänsten. Headern rapporterar teknisk information om bearbetningen i tjänsten. Headern följer elementet ProcessingStatus i XML Schemat: interoperability_headers_1.0.xsd.

Motiv: Ge tjänstekonsumenter möjligheten att verifiera att de fått ett komplett svar från den aggregerande tjänsten och om så inte är fallet kunna rapportera tillbaka till användaren att svaret bara är partiellt.

Exempel: Se ovan i kapitlet Syfte.

Regel #4: Aggregerande tjänster skall återanvända befintlig tjänsteinteraktion (WSDL-fil)

Aggregerande tjänster skall återanvända befintlig tjänsteinteraktion (WSDL-fil), dvs. använda samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder. Det medför att SOAP headern "ProcessingStatus" inte beskrivs explicit i de enskilda WSDL-filerna utan definieras istället i denna anvisning.

...



2021-03-12

Avpubliceras.

Innehåll flyttat till RIVTA Tekniska Anvisningar Basic Profile 2.1 och RIVTA Tekniska Anvisningar Tjänsteplattform

Anders MalmrosInera Arkitektur