Utgåvehistorik

...

1          Inledning

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

 Image Added

1.1          Målgrupp

...

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

...

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 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: Webblänk till PDF för REV B: http://www.cehis.se/arkitektur_och_regelverk/fordjupad_information/	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://www.cehis.se/arkitektur_och_regelverk/fordjupad_information/	Arkitektur och regelverk, Center för eHälsa i samverkan
[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. Webblänk till PDF för anvisningen: http://www.cehis.se/arkitektur_och_regelverk/fordjupad_information/	Arkitektur och regelverk, Center för eHälsa i samverkan
[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

...

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.

...

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

...

Motiv: Verktygsinteroperabilitet och följsamhet mot WS-I Basic Profile 1.1.

Exempel: Se exempel MakeBookingInteraction_1.1_RIVTABP21.wsdl [R9].

...

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

...

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

...

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

Motiv: Enhetlighet och koppling till referensarkitekturens terminologi 

Exempel: MakeBookingResponderBinding

...

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

Motiv: Enhetlighet och koppling till referensarkitekturens terminologi 

Exempel: MakeBookingResponderService

...

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

Motiv: Enhetlighet och koppling till referensarkitekturens terminologi

Exempel: MakeBookingResponderPort

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

...

Motiv: Konsekvent namngivning

Exempel: ” MakeBookingRequest” respektive ” MakeBookingResponse”

...

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

${operation}

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} 

Motiv: När man följer WS-I Basic Profile har soapAction-attributet på operatonsbindningen för soap-binding ingen praktisk verkan. Det är istället viktigt att Qualified Name för varje operations meddelande ger en unik signatur. Se WS-I Basic profile 1.1, Appendix C - operation signatur och R1127. För interoperabilitet med Microsoft .Net-baserade tjänsteproducenter (WCF) måste dock soapAction sättas till ett för ändpunkten unikt värde.

Denna regel anger att soapAction skall ha samma innehåll som "operation signature", vilket är tjänsteschemats namnrymd och elementnamnet på operationens "input message" (d.v.s. request-elementets namnrymd och namn). 

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

...

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

...

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

...

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

...

SOAP-adressen för en driftsatt tjänsteproducent (gäller även intermediära tjänster så som virtuella tjänster i tjänsteplattform) ska som del av URL:en ange rivta-profilens kortnamn och huvudversionen. Underversion få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

...

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

Varje tjänstekomponent som producerar tjänster (se definition i RIV TA Översikt) ska exponera en monitoreringstjänst enligt WSDL:en PingForConfigurationInteraction_1.x_RIVTABP21.wsdl, t.ex. PingForConfigurationInteraction_1.0_RIVTABP21.wsdl. PingForConfigurationInteraction ingår i tjänstedomänen itintegration:monitoring. Se tjänstekontraktsbeskrivning för itintegration:monitoring-domänen för ytterligare information om kontraktet.

Motiv: Möjliggöra enhetlig “health-check” av driftsatta tjänstekomponenter, samt möjliggöra avstämning av driftsatta tjänstekomponenters versionsinformation i samband med felrapporterting och felsökning. 

Exempel: Referensapplikationerna exponerar övervakningstjänsten (PingForConfiguration).