RIV Tekniska Anvisningar Basic Profile Valfria tillägg Version 1.1 ARK_0028
Innehåll 1 Översikt... 4 1.1 Tillgänglighet... 4 1.2 Referenser... 5 2 RIV Tekniska Anvisningar Basic Profile med http header för att ange ursprunglig avsändare 2.1... 7 2.1 Inledning... 7 2.1.1 Målgrupp... 7 2.1.2 Syfte... 7 2.2 Beskrivning av namnregler... 10 2.3 Följsamhet mot externa regelverk... 10 Regel #1, Följsamhet mot RIV TA BP 2.1... 10 2.4 Detaljerade regler... 10 Regel #2: Propagering av ursprunglig sändares identitet i http header... 10 Regel #3: Mottagande av ursprunglig sändares identitet i http header... 11 Regel #4: Säkerställ att anropande tjänsteplattform är känd... 11 3 RIV Tekniska Anvisningar Basic Profile med status för anrop till aggregerande tjänster 2.1... 12 3.1 Inledning... 12 3.1.1 Målgrupp... 12 3.1.2 Syfte... 12 3.2 Beskrivning av namnregler... 15 3.3 Följsamhet mot externa regelverk... 15 Regel #1, Följsamhet mot RIV TA BP 2.1... 16 3.4 Detaljerade regler... 16 Regel #2: Aggregerande tjänster skall returnera status om bearbetning av ett anrop... 16 Regel #3: Tjänstekonsumenter av en aggregerande tjänster kan ta del av status om bearbetning av ett anrop... 16 Regel #4: Aggregerande tjänster skall återanvända befintlig tjänsteinteraktion (WSDL-fil)... 16 2/16
Utgåvehistorik Utgåva PA1 Revision Datum Beskrivning Ändringarna gjorda av Definitiv revision fastställd av 2013-11-05 Första utgåva av anvisningar för magnus.larsson@inera.se valfria tillägg till RIV-TA v2.1. Innehåller: 1. Anvisning för att ange ursprunglig avsändare A 2. Anvisning för att ange status på bearbetning i aggregerande tjänst 2013-11-13 Uppdaterade mall och några typos Lars Erik Röjerås 1.1 Uppdaterat till Inera mall Lennart Eriksson 3/16
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. Översikt) Anvisning) Tjänste0 schema)2.1) Anvisning) Domän0 schema)2.1) Anvisning) Webservice0profil) 2.1) 0) Basic)Profile)med) valfria)>llägg) Baseras)på) Anvisning) Webservice0 profil)2.1) 0) Basic)Profile) 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 öppenkällkodslicensen Apache License, Version 2.0 (http://www.apache.org/licenses/license-2.0) 4/16
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 Bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av denna anvisning. Arkitektur och regelverk, Center för ehälsa i REV D Webblänk till PDF för översikten: samverkan http://rivta.se/documents/ark_0001 [R3] RIV Teknisk Anvisningen innehåller regeluppsättningen som definierar profilen. Arkitektur och regelverk, Anvisning - Basic Profile 2.1 Webblänk till PDF för anvisningen: http://rivta.se/documents/ark_0002 Center för ehälsa i samverkan [R4] RIV Teknisk Anvisning Anvisning för att specificera ett XML-schema (tjänsteschema) för ett tjänstekontrakt. Definierar elementen för WSDL-filens meddelanden. Arkitektur och regelverk, Center för ehälsa i Tjänsteschema 2.1 Webblänk till PDF för anvisningen: samverkan http://rivta.se/documents/ark_0005 [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 The Web Services Interoperability Organization och ISO Weblänk till WS-I Basic Profile: http://www.wsi.org/profiles/basicprofile-1.1.html [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 The Web Services Interoperability Organization Weblänk till profilen : http://www.wsi.org/profiles/simplesoapbindingprofile-1.0.html [R7] HCC spec. SITHS HCC: Certifikat för svensk vård och omsorg. Webblänk till PDF för REV 2.35: http:///tjanster-- PROJEKT/SITHS/ [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. Inera AB W3C Webblänk till specifikationens hemsida: http://www.w3.org/tr/2000/note-soap-20000508/ [R9] WSDL 1.1 spec Beskrivningsspråk för web-services. Syftar till att stödja utvecklingsverktyg W3C 5/16
Ref Dokument Beskrivning och ev. webbadress Ansvarig i design-time och web-service-konsumenter i run-time. Webbänk till specifikationens hemsida: http://www.w3.org/tr/wsdl [R10] Exempel - Tjänsteinteraktion [R11] Exempel konsument och producent i Java och.net 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 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 Arkitektur och regelverk, Center för ehälsa i samverkan 6/16
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 xrivta-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: 7/16
Klient certifikat Server certifikat Tjänstekonsument Tjänsteproducent 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: Request Klient certifikat NTjP certifikat HTTP header Server certifikat Tjänstekonsument Nationell Tjänsteproducent 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: 8/16
Klient certifikat Lokal TP certifikat Tjänstekonsument Applikationslokal Request HTTP header Request Request RTjP certifikat HTTP header NTjP certifikat HTTP header Server certifikat Regional Nationell Tjänsteproducent 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: 9/16
Klient certifikat NTjP certifikat Tjänstekonsument Nationell Request HTTP header RTjP certifikat Request HTTP header Lokal TP certifikat Request HTTP header Server certifikat Regional Applikationslokal Tjänsteproducent 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 10/16
En tjänsteplattform skall propagera ursprunglig avsändares identitet i http headern x-rivta-originalserviceconsumer-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 () 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 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 () i http headern och därmed otillåtet kan uppträda med dess identitet. 11/16
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: ProcessingStatus is used by aggregating services to report back to the consumer regarding the validity of the data returned. The following status codes are used to describe the quality of the data returned for a specific logicaladdress: 1. DataFromSource No data was available in cache, up-to-date data retrieved from source system 2. DataFromCache Up-to-date data returned from cache, no call performed to source system 3. DataFromCacheSynchFailed Required synch with source system failed. Potentially out-of-date data returned from Cache 4. NoDataSynchFailed No data returned, no data in cache and call to source system failed The following table describes the relationship between the status code element and the other elements in a processing-status-record: +--------------------------+---------------------+-------------------+--------------------------+-----------------------+----------------------------+ Status Code isresponsefromcache isresponseinsynch lastsuccessfulsynch lastunsuccessfulsynch lastunsuccessfulsyncherror +--------------------------+---------------------+-------------------+--------------------------+-----------------------+----------------------------+ DataFromSource False True Current timestamp Emtpy Empty DataFromCache True True Last time for succ. Empty Empty call DataFromCacheSynchFailed True False Last time for succ. call Current Relevant timestamp error info NoDataSynchFailed False False Empty Current timestamp Relevant error info +--------------------------+---------------------+-------------------+--------------------------+-----------------------+----------------------------+ 12/16
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: Tjänstekonsument 4 1 Response SOAP header Processing Status Aggregerande Tjänst 2 3a 3b Källsystem A Engagemangs- Index Källsystem B Givet att båda källsystemen svarar korrekt så kommer ProcessingStatus SOAP headern se ut något i stil med följande: 13/16
<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:header> <ProcessingStatus xmlns="urn:riv:interoperability:headers:1"> <ProcessingStatusList> <logicaladdress>-a</logicaladdress> <statuscode>datafromsource</statuscode> <isresponsefromcache>false</isresponsefromcache> <isresponseinsynch>true</isresponseinsynch> <lastsuccessfulsynch>20130904124333</lastsuccessfulsynch> </ProcessingStatusList> <ProcessingStatusList> <logicaladdress>-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): Tjänstekonsument 4 1 Response SOAP header Processing Status Aggregerande Tjänst 2 3a 3b Källsystem A Engagemangs- Index 3c Källsystem B Källsystem C 14/16
SOAP-headern ProcessingStatus kommer då se ut något i stil med följande: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:header> <ProcessingStatus xmlns="urn:riv:interoperability:headers:1"> <ProcessingStatusList> <logicaladdress>-a</logicaladdress> <statuscode>datafromsource</statuscode> <isresponsefromcache>false</isresponsefromcache> <isresponseinsynch>true</isresponseinsynch> <lastsuccessfulsynch>20130905111504</lastsuccessfulsynch> </ProcessingStatusList> <ProcessingStatusList> <logicaladdress>-b</logicaladdress> <statuscode>datafromsource</statuscode> <isresponsefromcache>false</isresponsefromcache> <isresponseinsynch>true</isresponseinsynch> <lastsuccessfulsynch>20130905111504</lastsuccessfulsynch> </ProcessingStatusList> <ProcessingStatusList> <logicaladdress>-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. 15/16
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. Motiv: SOAP headern beskrivs inte i de tjänsteinteraktioner (WSDL-filer) som en aggregerande tjänst följer, detta för att enkelt kunna återanvända samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder. Minskar kostnader och risk för fel i samband med vidareutveckling och förvaltning av tjänsteinteraktioner. 16/16