...
RIV Tekniska Anvisningar Basic Profile 2.1 Version 2.1.4 ARK_0002 2018-01-18 |
Utgåvehistorik
Utgåva | Revision Datum | Beskrivning | Ändringarna gjorda av | Definitiv revision fastställd av |
PA1 | 2011-04-27 | Skapat dokument med bas i RIV TA 2.0 samt införlivat begärda ändringar enligt trackers på http://forge.osor.eu/projects/rivta: 1009, 1097, 2403, 14243, 14633, 15114, 15176 | marcus.krantz@callistaenterprise.se | |
PA2 | 2011-10-17 | Korrektur | ||
A | 2011-10-18 | Fastställd revision. | Arkitektur-ledningens tekniska expertgrupp | |
PB1 | 2011-12-14 | Uppdaterat dokumentet i och med byte av projektplats från Osor till Google code. Enbart ändringar under rubriken Referenser. | ||
B | 2012-01-03 | Fastställd revision. | Arkitektur-ledningens tekniska expertgrupp | |
C | 2013-06-19 | Ny revision efter CeHis nya processer | Arkitektur och regelverk, Center för eHälsa i samverkan | Arkitektur och regelverk, Center för eHälsa i samverkan |
2.1.1. | 2014-09-25 | Ny mall samt publicerad. | Lennart Eriksson Inera | |
2.1.2. | 2015-04-02 | Regel #22 tillagd | Johan Eltes Inera | Inera A&R |
2.1.2 | 2015-05-28 | Ny version fastställd | Inera A&R | |
2.1.3 | 2015-12-22 | Uppdaterat länkar i referenstabell. Regel #19 (ang. format på URL) ändrad från ”skall” till ”bör”, då denna detalj inte påverkar interoperabiliteten samt baserat på den faktiska användningen. | Mattias Nordvall, Inera | Inera A&R |
| 2.1.4 | 2018-01-18 | Uppdaterat regel #21, kravet på övervakningstjänst har utgått | Björn Hedman | Inera A&R |
| 2.1.5 | 2018-03-05 | Ändrat namn till RIV Tekniska Anvisningar Basic Profile 2.1 från RIVTA Basic Profile 2.1 för följa övrig namnstandard | Björn Hedman |
| 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:
...
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.
1.3 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 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: | 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. | 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. | 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}
...
- Tjänstedomänens namn: ${tjänsteDomän}, t ex clinicalprocess:activity:request
- Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex GetRequestStatus
- Tjänsteinteraktionsroll: ${roll} = Initiator eller Responder, motsvarande tjänsteinteraktionsroller initiativtagare och utförare
- Tjänsteinteraktionens version:
m.n = förkortning av ${majorVersion}.${minorVersion}
m = förkortning av ${majorVersion} - 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>
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:
...
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.
...
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:
...
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.
...
<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)
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:
...