Image Removed

Image Added

RIV Tekniska  Anvisningar

Basic Profile 2.1 Version 2.1.6 ARK_0002 2021-03-12

1. Inledning

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

...

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

...

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

• Stöd för de typer av tjänsteinteraktioner som anges i T-bokens referensarkitektur

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.

...

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

2. Beskrivning av namnregler

...

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

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

...

Exempel: MakeBookingInteraction_1.0_RIVTABP21.wsdl

Regel #3, namn på <definitions>-element

Name-attributet för elementet wsdl:definitions bör ges värde enligt följande regel: ${tjänsteInteraktion}Interaction

...

Exempel: MakeBookingInteraction

Regel #4, namn på target namespace

Namn på target namespace skall vara urn:riv:${tjänsteDomän}:${tjänsteInteraktion}:m:${profilKortnamn}

...

Exempel: urn:crm:scheduling:MakeBooking:1:rivtabp21

Regel #5 – Dokumentation av tjänsteinteraktion

Första elementet under wsdl:definitions bör dokumenteras enligt följande uppställning:

<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:

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

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

     </wsdl:documentation>

Regel #6 – Kryptering och Autentisering

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

...

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"

• "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. Se RIV Teknisk anvisning – Tjänsteschema [R3] fö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.

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.

• 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 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 adresseras på verksamhetsnivå. Den verksamhetsmässiga adressaten (den logiska adressen) uttrycks med hjälp av verksamhetens HSA-id eller 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.

...

Exempel: MakeBookingResponderInterface

Regel #10, namn på <binding>-element

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

...

Exempel: MakeBookingResponderBinding

Regel #11, namn på <service>-element

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

...

Exempel: MakeBookingResponderService

Regel #12, namn på <port>-element

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

...

Exempel: MakeBookingResponderPort

Regel #13, namn på <message>-element

Name-attributet för elementet wsdl:message skall ha värde enligt följande regler:

• In-meddelande skall namnges ${operation}Request

• Ut-meddelande skall namnges ${operation}Response

Motiv: Konsekvent namngivning

Exempel: ” MakeBookingRequest” respektive ” MakeBookingResponse”

Regel #14, namn på <operation>-element

Name-attributet för elementet wsdl:operation skall ha värde enligt följande regel:

...

Motiv: Konsekvent namngivning

Exempel: MakeBooking

Regel #15, värde för soapAction-attribut

soapAction-attributet för elementet soap:operation skall ha värde enligt följande regel: urn:riv:${tjänsteDomän}:${tjänsteInteraktion}${roll}:m:${operation}

...

Exempel: urn:riv:crm:scheduling:MakeBookingResponder:1:MakeBooking

Regel #16, targetNamespace i schema:import

Vid import av scheman i WSDL-filen skall targetNamespace anges för xs:schema-elementet. Värdet på targetNamespace-attributet skall vara samma som WSDL:ens targetNamespace.

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 elementet. 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: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.

...

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.

...

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.

...

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)

...

En tjänstekonsument har möjlighet att informera om att de utför ett anrop på uppdrag av annan part genom att bifoga en http header “x-rivta-acting-on-behalf-on-hsaid”. Informationsinnehållet i denna header skall, om det används, vara ett HSA id. Detta är ett frivilligt informativt fält som endast får sättas av ursprunglig tjänstekonsument. En tjänsteproducent kan välja att anpassa sitt svar utifrån denna information.

...

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. 

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

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

...

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.

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

Tjänstekonsumenter av en aggregerande tjänster 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.

...