Image Removed

Image Added

RIV

Tekniska  Anvisningar

Tekniska Anvisningar Basic Profile 2.1 Version

2

3.

1.9

0 ARK_0002

2023

2024-

05

09-

09

18

Innehållsförteckning

1. Inledning

Detta dokument beskriver regelverket för RIV Tekniska Anvisningar Basic Profile 2.1.

...

1.1 Målgrupp

Denna anvisning riktar sig till dem som ska specificera WSDL för en nationell tjänsteinteraktion i enlighet den tekniska RIV-profil som benämns Basic Profile. Anvisningen innehåller endast regeluppsättningen som definierar profilen. 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.0 [R2].

1.2 Syfte

Syftet med denna anvisning är att beskriva hur man realiserar utbytet av information mellan två parter på ett interoperabelt sätt baserat på WS-I Basic Profile v1.1 för de typer av tjänsteinteraktioner som anges i T-boken:

...

Regler och riktlinjer för framtagning av WSDL-filer

...

Baserad på RIV Teknisk anvisning – Tjänsteschema [R3]

...

Baserad på WS-I Basic Profile v1.1 [R4] och WS-I Simple SOAP Binding Profile v1.0 [R5]

...

Protokollbaserad säkerhet, HTTPS, med användande av ömsesidig autentisering för säker identifiering av sändande tjänstekomponent

...

Riktlinjer för versionshantering av WSDL

...

1. Inledning

Detta dokument beskriver regelverket för RIV-profilen Basic Profile 2.1.

För ytterligare beskrivning av RIV-profiler se anvisningen RIV Tekniska Anvisningar SOAP Webservices

...

1.1 Målgrupp

Denna anvisning riktar sig till dem som ska specificera WSDL för en nationell tjänsteinteraktion i enlighet den RIV-profil som benämns Basic Profile. Anvisningen innehåller endast regeluppsättningen som definierar profilen.

1.2 Syfte

Syftet med denna anvisning är att beskriva hur man realiserar utbytet av information mellan två parter på ett interoperabelt sätt baserat på WS-I Basic Profile v1.1 för de typer av tjänsteinteraktioner som anges i T-

...

Exempel på WSDL som följer denna anvisning finns på RIV-förvaltningens hemsida [R9] tillsamman med exempelapplikationer [R10] som visar hur konsumenter och producenter kan utvecklas i Java och .Net för tjänsteinteraktioner som följer denna profil.boken.

För bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av profilen hänvisas till RIV Tekniska Anvisningar SOAP Webservices.

1.3 Tillgänglighet

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

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

1.4 Referenser

...

Ref

...

Dokument

...

Beskrivning och ev. webbadress

...

Ansvarig

...

[R1]          

...

T-Boken

...

VITS-bokens tekniska arkitektur. Styrande tekniska principer och teknisk referensarkitektur för den nationella arkitekturen:

http://rivta.se/documents/ARK_0019/

...

Arkitektur och regelverk, Inera

...

[R2]          

...

Översikt RIV Tekniska Anvisningar REV D

...

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

http://rivta.se/documents/ARK_0001/

...

Arkitektur och regelverk,Inera

...

[R3]          

...

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.

http://rivta.se/documents/ARK_0005/

...

Arkitektur och regelverk, Inera

...

[R4]          

...

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

...

[R5]          

...

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

...

[R6]          

...

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

...

[R7]          

...

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

...

[R8]          

...

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

...

[R9]          

...

Exempel - Tjänsteinteraktion

...

All 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.

Webblänk till tjänsteinteraktionens WSDL och XML-scheman: http://code.google.com/p/rivta/source/browse/RefApp/rivta-bp-21/java/cxf/trunk/rivta-bp21-refapp-schemas/src/main/resources/schemas/

...

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

...

[R10]        

...

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.

Webblänk till hemsida för exempelapplikationer: http://code.google.com/p/rivta/wiki/Bp21ReferenceApplication

...

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

2. Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile 2.1” och refereras ${profil}

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

Namngivningsregler i detta dokument är formulerade enligt följande uppställning:

1. Tjänstedomänens namn: ${tjänsteDomän}, t ex clinicalprocess:activity:request

2. Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex GetRequestStatus

3. Tjänsteinteraktionsroll: ${roll} = Initiator eller Responder, motsvarande tjänsteinteraktionsroller initiativtagare och utförare

4. Tjänsteinteraktionens version:
   m.n = förkortning av ${majorVersion}.${minorVersion}
   m = förkortning av ${majorVersion}

5. Operationens namn: ${operation}, t ex GetRequestStatus

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 WS-I-profiler

Utforming av WSDL skall följa WS-I Basic Profile v1.1 [R4] och WS-I Simple SOAP Binding Profile v1.0 [R5].

Motiv: Interoperabilitet

4. Detaljerade regler

Regel #2, Namngivning av WSDL-fil

...

2. Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile 2.1” och refereras ${profil}

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

Namngivningsregler i detta dokument är formulerade enligt följande uppställning:

1. Tjänstedomänens namn: ${tjänsteDomän}, t ex clinicalprocess:activity:request

2. Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex GetRequestStatus

3. Tjänsteinteraktionsroll: ${roll} = Initiator eller Responder, motsvarande tjänsteinteraktionsroller initiativtagare och utförare

4. Tjänsteinteraktionens version:
   m.n = förkortning av ${majorVersion}.${minorVersion}
   m = förkortning av ${majorVersion}

5. Operationens namn: ${operation}, t ex GetRequestStatus

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 WS-I-profiler

Utforming av WSDL skall följa WS-I Basic Profile v1.1 (WS-I Basic Profile - Version 1.1) och WS-I Simple SOAP Binding Profile v1.0 (Simple WS-I SOAP Binding Profile - Version 1.0).

Motiv: Interoperabilitet

3.1 Förtydligad hantering av SOAP Fault

Tekniska fel återrapporteras med ett svarsmeddelande utformat som ett SOAP Fault i enlighet med WS-I.

SOAP-standarden, vilken WS-I bygger på, definierar fyra generella felkoder:

1. VersionMismatch

2. MustUnderstand

3. Client

4. Server

Ur en tjänsteproducents perspektiv är Client och Server mest intressanta. Faultcode=’soap:Client’ betyder att det är fel på tjänstebegärans innehåll eller dess kontext (exempelvis klientcertifikat eller konsumentens åtkomstbehörighet), och att omsändning inte ska ske utan felkorrigerande åtgärd på konsumentsidan. Faultcode=’soap:Server’ betyder att behandlingen gått fel, men det var inget fel på begäran i sig och omsändning kan ske.

Det rekommenderas att hålla sig till de generella felkoderna, men om man för ett tjänstekontrakt absolut behöver definiera egna felkoder med finare granularitet, skall dessa definieras i en separat namnrymd. Konsumentens förväntade agerande baserat på dessa felkoder måste finnas tydligt beskrivna i tjänstekontraktsbeskrivningen.

Exempel:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:myservice="http://schemas.inera.se/faultcodes/">
    <soap:Header/>
    <soap:Body>
        <soap:Fault>
            <faultcode>myservice:Server.connectFailure</faultcode>
            <faultstring>Connection to resource failed</faultstring>
            <detail><xs:string xmlns:xs="http://www.w3.org/2001/XMLSchema">instance prdtccgmx01 cannot connect to prdtccgmxdb</xs:string></detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

Information i SOAP Faults bör loggas av tjänstekonsumenten. Informationen är inte riktad till användaren utan till systemförvaltaren. Detaljinformationen från ett SOAP Fault är normalt sett inte avsett att visas för användaren utan riktar sig till systemförvaltaren via loggning.

Felbeskrivning i fälten faultstring och detail ska innehålla tillräcklig information för att driva felsökningen framåt. Om det till exempel finns identifieringsbegrepp eller loggid som kan underlätta felsökning skall dessa inkluderas.

Fältet faultactor kan användas i enighet med SOAP-standarden, men dess utformning och användning definieras ej av RIV-TA utöver SOAP-standardens riktlinjer.

Exempel:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header/>
    <soap:Body>
        <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Informationsinhämtning med GetClinicalChemistryLabOrderOutcome från SE2321000016-93GN misslyckades. Referera till loggid="c5ad1e04-d5af-4483-bf21-607524bc7b0d" vid felsökning</faultstring>
            <faultactor>http://cgm.sll.se</faultactor>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

3.2 Förtydligad hantering av http headrar

Headrar ska alltid tolkas skiftlägesokänsligt i enlighet med specifikationen för http. Se https://www.ietf.org/rfc/rfc2616.html#section-4.2 för detaljer

4. Detaljerade regler

Regel #2, Namngivning av WSDL-fil

WSDL-filen bör namnges enligt följande regel: ${tjänsteInteraktion}Interaction_${m.n}_${profilKortnamn}.wsdl

Motiv: Minska risk för missförstånd rörande vilken version som används

...

<wsdl:documentation>
           Tjänsteinteraktionens namn: ${tjänsteInteraktion}
           Beskrivning: ${beskrivande text för tjänsteinteraktionen}
           Revisioner:
              ${datum för version m.n} Version ${m.n} i lista
           Tjanstedoman: ${tjänsteDomän}
           Tjansteinteraktionstyp:
              Ett av Fraga-svar, Informationsspridning, Uppdrag-resultat
           RIV Teknisk Anvisning: ${profil}
           Forvaltning:
              Referens till information om förvaltningsprocess för
              tjänsteinteraktionen
     </wsdl:documentation>

Motiv:Underlätta användning och förvaltning.

Exempel:

...

<wsdl:documentation>

...

           Tjänsteinteraktionens namn: MakeBookingInteraction

...

           Beskrivning:

...

              Interaction to make a new booking at a healthcare facility.

           Revisioner:

...

              Interaktion för att göra en ny bokning på en vårdenhet.
           Revisioner:
              2009-10-26: Utkast Version 1.0,

...

 <person>@<organisation>
              2010-04-21: Fastställd version 1.0, <person>@<organisation>

...

              2011-03-XX: Fastställd version 1.1, <person>@<organisation>

...

                         - Se ändringslog i tjänsteschema

...

           Tjänstedomän: crm:scheduling

...

           Tjänsteinteraktionstyp: Fråga-svar

...

           RIV Teknisk Anvisning: Basic Profile 2.

...

1
           Förvaltas av: Mina Vårdkontakter inom Inera AB    

...

     </wsdl:documentation>

Regel

...

HTTPS med ömsesidig autentisering skall användas för autentisering av tjänsteproducent och tjänstekonsument samt för kryptering av meddelandeutbyte.

Motiv: Insynsskydd, oavvislighet m.a.p. parternas identitet och möjlighet för tjänsteproducent att verifiera teknisk anropsbehörighet.

Exempel: Exempelapplikationer visar hur https med ömsesidig autentisering kan upprättas för prioriterade plattformar [R10].

Regel #7 – Document/Literal

För konsistent namngivning och ökad förståelse skall följande regler följas:

...

"SOAP binding style" skall sättas till "document"

...

#7 – Document/Literal

För konsistent namngivning och ökad förståelse skall följande regler följas:

• "SOAP binding style" skall sättas till "document"

• "SOAP body use" skall sättas till "literal"

• Varje wsdl:message skall ha en och endast en wsdl:part för soap-bodyn, som skall vara namnsatt till "parameters"

• Varje message-element som inte är av schema-grundtyp skall referera till ett XML Schema element ur ett importerat (xsd:import) tjänsteschema ur samma tjänsteinteraktion som denna WSDL.

• XML Schema-elementet för "input message" skall vara namnsatt till operationens namn. SeRIV Teknisk anvisning – Tjänsteschema [R3] Tekniska Anvisningar - Tjänsteschema 2.1för definition av element som refereras från wsdl:message

• XML Schema elementet för "output message" skall vara namnsatt till operationens namn + suffix "Response". Se RIV Teknisk anvisning – Tjänsteschema [R3] för definition av element som refereras från wsdl:message. RIV Tekniska Anvisningar - Tjänsteschema 2.1

Motiv: Verktygsinteroperabilitet och följsamhet mot WS-I Basic Profile 1.1.Exempel: Se exempel MakeBookingInteraction_ 1.1_RIVTABP21.wsdl [R9].

Regel #8: Logisk adressering

Elementet {urn:riv:itintegration:registry:1}LogicalAddress skall användas för att i soap-header ange logisk adressat.

• Tjänstekonsument skall ange logisk adress för adresserad tjänsteproducent. För utformning av logiska adresser hänvisas till RIV-TA Översikt

• WSDL:en skall importera (xs:import) följande schema för namnrymd "urn:riv:itintegration:registry:1" som bör ges namnrymdsalias "riv": itintegration_registry_1.n.xsd, t.ex. itintegration_registry_1.0.xsd

• Det första wsdl:Part-elementet i varje wsdl:Message som definierar ett request-meddelande skall ha namnet LogicalAddress och värdet "riv:LogicalAddress" för attributet "element".

• Varje LogicalAddress-part enligt ovan skall bindas till soap:header under wsdl:binding / wsdl:operation / wsdl:input.

• Tjänstekonsumenten skall tilldela HSA-id för adresserad verksamhet. För verksamheter med tilldelad HSA-id, ska detta användas. Där sådant saknas, används identitet ur annat tillämpbart kodverk. Den generella principen om verksamhetsadress gäller dock fortfarande.

• Varje Varje wsdl:operation ska föregås av en wsdl:documentation som ger utvecklare av tjänstekonsumenter och tjänsteproducenter vägledning om eventuella begränsningar avseende LogicalAddress. Den kan t.ex. vara att HSA-id måste vara på nivån Enhet, eller att det måste vara en administrativ huvudman med ansvar för medborgares vårdval.

Motiv: T-bokens referensarkitektur definierar en adresseringsmodell där tjänsteproducenter antingen adresseras på verksamhetsnivå eller systemnivå. Den verksamhetsmässiga adressaten (den logiska adressen ) uttrycks till exempel med hjälp av verksamhetens eller systemets HSA-id eller alternativt annat tillämpbart kodverk i enlighet med respektive domäns tjänstekontraktsbeskrivning. En tjänstekonsument ska alltid utgå ifrån att anropad tjänsteproducent är virtuell (intermediary) med uppgift att dirigera meddelandet till den tjänsteproducent som adresserad verksamhet använder för ändamålet (ändamålet uttrycks av rotelementets kvalificerade namn – d.v.s. tjänstekontraktets namnrymd + operationens namn). Detta gäller i alla led - alltså även vid federerade arkitekturer där en virtuell tjänst i en samverkansdomän (t.ex. nationella domänen) dirigerar ett meddelande till en tjänsteproducent som i själva verket visar sig vara en virtuell tjänst i en annan samverkansdomän (t.ex. en regional domän). För mer information kring adresseringsmodellen och federerad tjänsteplattform hänvisas till T-boken.

Exempel: Se exempel MakeBookingInteraction_1.0_RIVTABP21.wsdl [R9] och exempelkod för tjänstekonsumenter [R10].

Regel #9, namn på <portType>-element

Name-attributet för elementet wsdl:portType bör ha värde enligt följande regel: ${tjänsteInteraktion}${roll}Interface.

Motiv: Enhetlighet och koppling till referensarkitekturens terminologi

Exempel:

För ytterligare detaljer kring adresseringsmodellen se RIV-TA Översikt

Regel #9, namn på <portType>-element

Name-attributet för elementet wsdl:portType bör ha värde enligt följande regel: ${tjänsteInteraktion}${roll}Interface.

Motiv: Enhetlighet och koppling till referensarkitekturens terminologi

Exempel: MakeBookingResponderInterface

...

Motiv: WS-I Basic Profile kräver ej den här ändringen men Microsoft’s BizTalk kan inte importera WSDL-filen om inte targetNamespace anges på xs:schema elementetvissa ramverk har historiskt krävt att targetNamespace specificeras så för ökad interoperabilitet kräver vi det i Basic Profile. Av den här anledningen skall man alltid ange targetNamespace för att få ökad interoperabilitet. WS-I tillåter inte att targetNamespace är samma som det importerade schemats namnrymd.

Exempel:

<wsdl:types>

...

       <xs:schema targetNamespace="urn:riv:crm:scheduling:MakeBooking:1:rivtabp21">

...

       <xs:import schemaLocation="MakeBookingResponder_1.1.xsd" namespace="urn:riv:crm:scheduling:MakeBookingResponder

...

</wsdl:types>

Regel #17, Förhållandet mellan porttype och operationer

Endast en operation per porttype och en porttype per tjänsteschema. Det betyder att en wsdl-fil antingen har en eller två porttypes: WSDL-filen för en fråga-svar-interaktioner och en informationsspridningsinteraktioner har en porttype medan uppdrag-resultat-interaktioner har två porttypes.

Motiv: Möjliggöra versionshanteringstrategin som beskrivs i RIVTA Översikt

Exempel: Se WSDL för referensapplikationen

5. Tjänstekomponenter

Regel #18, WSDL-first

Tjänstekonsumenter och tjänsteproducenter skapas genom s.k. “wsdl-first”. Det betyder att WSDL-filen för tjänsteinteraktionen definierar hur tjänsteproducentens gränssnitt ser ut, vanligen genom kodgenerering från WSDL-fil. Det samma gäller tjänstekonsumenter.

Motiv: Säkerställa att tjänstekomponenter följer interaktionens tjänstekontrakt.

Exempel: Se kodgenereringsskript för referensapplikationen

Regel #19, Uppbyggnad av URL för tjänsteproducent

SOAP-adressen för en driftsatt tjänsteproducent (gäller även intermediära tjänster så som virtuella tjänster i tjänsteplattform) bör som del av URL:en ange rivta-profilens kortnamn och huvudversionen. Underversion bör ej anges i URL:en.

Motiv: Möjliggöra realisering av den versionsstrategi som stödjs av tjänstekontrakt som tagits fram enligt denna profil samt att parallellt erbjuda stöd för flera RIVTA-versioner mot samma tjänst (t.ex. rivtabp21 och rivtabpip21).

Exempel: https://tidbok.landsting.sjunet.org/MakeBooking/1/rivtabp21

Regel #20, Meta-data i run-time

Det är INTE obligatoriskt för en tjänsteproducent att i runtime (t.ex. med “?wsdl” som suffix på soap-adressen) kunna återskapa den WSDL som låg till grund för utvecklingen av tjänsteproducenten.

Motiv: Alla plattformar förmår inte återskapa metadata i runtime för tjänster som följer denna profil (t.ex. vissa .Net-versioner och versioner av BizTalk server). Det är inget problem eftersom tjänstekonsumenten ska utvecklas “wsdl-first” baserat på WSDL-fil – inte på runtime-metadata från tjänsten själv.

Regel #21, Övervakningstjänst Utgått

Kravet på övervakningstjänst har utgått (januari 2018)

Regel #22, Förnyade anropsförsök vid tillfälligt otillgänglig tjänsteproducent

Denna regel rör tjänstekonsumenter som genomför anrop i någon form av bakgrundsprocess med krav på förnyade anropsförsök vid tillfälligt otillgängliga tjänsteproducenter:

1) Förnyade anropsförsök får inte resultera i högre anropsfrekvens än vad SLA för aktuellt tjänstekontrakt tillåter under normal drift (tillgänglig tjänsteproducent).

2) Om tjänstekonsumenten anropar olika logiska adressater via en virtuell tjänst kan olika anrop nå olika bakomliggande tjänsteproducenter. Under sådana omständigheter ska tjänstekonsumentens logik vara utformad så att omsändning till en otillgänglig adressat inte blockerar väntande anrop med andra adressater eftersom dessa kan komma att dirigeras till en tillgänglig tjänsteproducent.

3) SLA-regelverket för en tjänstekonsument ska vara uttryckt på ett sätt som gör det möjligt att förutsäga vilken anropsfrekvens som är möjlig för en tjänstekonsument, så att tjänstekonsumenten kan säkerställa att punkten 1 ovan efterlevs.

Motiv: Att undvika DoS-liknande anropsmönster i samband med otillgänglig tjänsteproducent.

Exempel: En policy för förnyade anropsförsök kan t.ex. upprätthållas genom att tjänstekonsumenten använder en intern meddelande-kö som betas av, av en eller flera parallella processer eller trådar. Om varje sådan parallell hantering läser från början av kön, anropar tjänsteproducenten i den takt som tillåts enligt SLA och vid otillgänglig tjänsteproducent skriver tillbaka meddelandet sist på kön. Innan meddelandet som resulterade i felaktigt anrop åter hamnar först har alla väntande meddelanden hanterats. På så viss vis sker förnyade anropsförsök kontinuerligt men utan att anrop till tillgängliga tjänsteproducenter blockeras. Beroende på applikationsspecifika krav kan det eventuellt vara idé att istället hantera misslyckade anrop i en separat kö och låta dem cirkulera där tills berörda tjänsteproducenter blivit tillgängliga och anropen kunnat genomföras.

Regel #23: 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å reda 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.

Exempel: En tjänsteproducent sitter bakom 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änsteplattformen som fångar upp identiteten från tjänstekonsumentens klientcertifikat och sätter det i http headern. Den regionala tjänsteplattformen för bara vidare inkommande http header till sitt utgående anrop till tjänsteproducenten.

Regel #24: Information om uppdragsgivande part

...

:1"/>
</wsdl:types>

Regel #17, Förhållandet mellan porttype och operationer

Endast en operation per porttype och en porttype per tjänsteschema. Det betyder att en WSDL-fil antingen har en eller två porttypes: WSDL-filen för en fråga-svar-interaktioner och en informationsspridningsinteraktioner har en porttype medan uppdrag-resultat-interaktioner har två porttypes.

Motiv: Möjliggöra versionshanteringstrategin som beskrivs i RIVTA Översikt

5. Tjänstekomponenter

Regel #18, WSDL-first

Tjänstekonsumenter och tjänsteproducenter skapas genom s.k. “WSDL-first”. Det betyder att WSDL-filen skapas först och sedan nyttjas som underlag för kodgenerering av tjänstekomponenternas implementation.

Motiv: Säkerställa att tjänstekomponenter följer interaktionens tjänstekontrakt.

Regel #19, Uppbyggnad av URL för tjänsteproducent Utgått

Regel #29, Stöd för parallella huvudversioner

En tjänsteproducent som behöver erbjuda stöd för parallella huvudversion behöver ha en metod för att kontrollera vilken huvudversion som ett anrop avser. Detta kan göras genom att kontrollera SOAP-headern för namespace för att fastställa vilket tjänstekontrakt och vilken version som används i en interaktion. Alternativ metod kan vara att separera versioner med url:ens utformning.

Motiv: Möjliggöra realisering av den versionsstrategi som stödjs av tjänstekontrakt som tagits fram enligt denna profil samt att parallellt erbjuda stöd för flera tjänster baserade på olika huvudversioner av samma tjänstekontrakt

Exempel:

Separation via namespace: urn:riv:crm:scheduling:CancelBooking:1:rivtabp21

Separation via url: https://tidbok.landsting.sjunet.org/MakeBooking/1/rivtabp21

Regel #20, Meta-data i run-time

Det är INTE obligatoriskt för en tjänsteproducent att i runtime (t.ex. med “?wsdl” som suffix på soap-adressen) kunna återskapa den WSDL som låg till grund för utvecklingen av tjänsteproducenten.

Motiv: Alla plattformar förmår inte återskapa metadata i runtime för tjänster som följer denna profil (t.ex. vissa .Net-versioner och versioner av BizTalk server). Det är inget problem eftersom tjänstekonsumenten ska utvecklas “wsdl-first” baserat på WSDL-fil – inte på runtime-metadata från tjänsten själv.

Regel #21, Övervakningstjänst Utgått

Regel #22, Förnyade anropsförsök vid tillfälligt otillgänglig tjänsteproducent

Denna regel rör tjänstekonsumenter som genomför anrop i någon form av bakgrundsprocess med krav på förnyade anropsförsök vid tillfälligt otillgängliga tjänsteproducenter:

1. Förnyade anropsförsök får inte resultera i högre anropsfrekvens än vad SLA för tjänsten tillåter under normal drift. För automatiserad omsändningsstrategi rekommenderas ökande omsändningsintervall för att inte belasta nät och producentsystem i onödan.

2. Om tjänstekonsumenten anropar olika logiska adressater via en virtuell tjänst kan olika anrop nå olika bakomliggande tjänsteproducenter. Under sådana omständigheter ska tjänstekonsumentens logik vara utformad så att omsändning till en otillgänglig adressat inte blockerar väntande anrop med andra adressater eftersom dessa kan komma att dirigeras till en tillgänglig tjänsteproducent.

3. SLA-regelverket för en tjänstekonsument ska vara uttryckt på ett sätt som gör det möjligt att förutsäga vilken anropsfrekvens som är möjlig för en tjänstekonsument, så att tjänstekonsumenten kan säkerställa att punkt 1 ovan efterlevs.

4. Bedömning av om förnyat anropsförsök ska göras beror på om felet anses vara av tillfällig natur till exempel vid en time out, felkod vp009 eller ett annat tekniskt fel. vid andra fel som till exempel vp007 så kräver felet åtgärd innan det är ide med omsändning.

5. Respektive tjänstekontraktsbeskrivning kan ytterligare definiera regler kring omsändning.

Motiv: Att undvika DoS-liknande anropsmönster i samband med otillgänglig tjänsteproducent.

Exempel: En policy för förnyade anropsförsök kan t.ex. upprätthållas genom att tjänstekonsumenten använder en intern meddelande-kö som betas av, av en eller flera parallella processer eller trådar. Om varje sådan parallell hantering läser från början av kön, anropar tjänsteproducenten i den takt som tillåts enligt SLA och vid otillgänglig tjänsteproducent skriver tillbaka meddelandet sist på kön. Innan meddelandet som resulterade i felaktigt anrop åter hamnar först har alla väntande meddelanden hanterats. På så viss vis sker förnyade anropsförsök kontinuerligt men utan att anrop till tillgängliga tjänsteproducenter blockeras. Beroende på applikationsspecifika krav kan det eventuellt vara idé att istället hantera misslyckade anrop i en separat kö och låta dem cirkulera där tills berörda tjänsteproducenter blivit tillgängliga och anropen kunnat genomföras.

Regel #23: Mottagande av ursprunglig tjänstekonsuments identitet i http header

En tjänsteproducent kan utnyttja http-headern ”x-rivta-original-serviceconsumer-hsaid” för att få reda på identiteten av den ursprungliga tjänstekonsumenten.

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

Exempel: En tjänsteproducent sitter bakom en regional tjänsteplattform. Tjänstekonsumenten anropar den nationella tjänsteplattformen som i sin tur anropar den regionala. Det blir nu den nationella tjänsteplattformen som fångar upp identiteten från tjänstekonsumentens klientcertifikat och sätter det i http-headern. Den regionala tjänsteplattformen för bara vidare inkommande http-header till sitt utgående anrop till tjänsteproducenten.

Regel #24: Information om uppdragsgivande part

En tjänstekonsument (som identifieras av ”x-rivta-original-serviceconsumer-hsaid”) ska, om de utför ett anrop på uppdrag av annan part, informera om detta. Detta görs genom att tjänstekonsumenten bifogar http-headern “x-rivta-acting-on-behalf-of-hsaid”. Informationsinnehållet i denna header ska vara ett HSA-id som representerar den uppdragsgivande verksamheten.

Tjänsteproducenter kan använda informationen till att begränsa åtkomst till tjänsten eller anpassa returnerat informationsomfång.

Motiv: Detta ger en möjlighet för tjänsteproducenter att identifiera uppdragsgivande verksamhet bakom en tjänstekonsuments anrop om man vill ha en mer fingranulär åtkomstkontroll än att bara basera sig på ursprunglig tjänstekonsument.

Exempel: Ett anrop som sker från ett agentsystem för en viss verksamhets räkning indikerar denna uppdragsgivande verksamhets HSA-id i http-headern. Tjänsteproducenten kan då ta beslut om att samverka med vissa utvalda verksamheter som nyttjar samma agents system.

Regel #28: Hantering av nekad åtkomst

Nekade åtkomstbeslut ska resultera i ett av tre olika svar enligt nedan beroende på var i anropskedjan felet uppstår:

• Om första tjänsteplattform nekar teknisk åtkomst till tjänsteplattformen själv ska det resultera i att felkod HTTP 403 Forbidden returneras.

  • Exempelvis att den anropande tjänstekonsumenten använder ett ogiltigt certifikat eller på andra grunder nekas anslutning

• En tjänsteplattforms virtualiseringsplattformskomponent som själv tar beslut om nekad åtkomst ska returnera detta fel som ett SOAP Fault med kod VP007 i felmeddelandet.

  • Exempelvis om det saknas en giltig anropsbehörighet i TAK

• Beslut om nekad åtkomst som tas av en faktisk tjänsteproducent ska resultera i att felkod HTTP 403 Forbidden returneras.

  • Exempelvis om en tjänsteproducent baserar åtkomst på riv-ta headrar enligt reglerna #23 och #24

• En tjänsteplattforms virtualiseringsplattformskomponent som tar emot en HTTP 403 Forbidden ska omvandla detta fel till ett SOAP Fault med kod VP016 i felmeddelandet.

Motiv: Detta underlättar för tjänstekonsumenter att hantera felsituationer baserade på saknad åtkomstbehörighet och även urskilja denna felorsak från andra.

Exempel: Ett anrop för informationsförsörjning vid kvalitetsregisterrapportering via NKRR-systemet kan få ökad förståelse vid felsituationer när faktiska tjänsteproducenter vitlistat anrop från specifika registerplattformar.

Regel #6 – Kryptering och Autentisering

HTTPS med ömsesidig autentisering (mutual TLS) skall användas för autentisering av tjänsteproducent och tjänstekonsument samt för kryptering av trafiken mellan parter som tillhör olika organisationer.

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

Motiv: Insynsskydd, oavvislighet med avseende på parternas identitet, samt möjlighet för tjänsteproducent att verifiera teknisk anropsbehörighet.

6. Status för anrop till aggregerande tjänster

6.1 Syfte

Syftet med denna anvisning är att beskriva Nedan beskrivs 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.regel #25. 

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 -headern ”ProcessingStatus” ingår. Detta illustreras av följande bild:

...

Om något av de anropade källsystemen inte svarar inom en föreskriven tid eller returnerar ett fel så kommer ProcessingStatusSOAP-SOAP headern ProcessingStatus innehålla information om att svaret inte är komplett utan bara partiellt samt information om vilket fel som uppstod.

...

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: -schemat interoperability_headers_1.0.xsd.

...

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: -schemat interoperability_headers_1.0.xsd.

...

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 istället 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.