Open	RIV Tekniska Anvisningar SOAP Webservices   Version 1.0 ARK_0069 2024-09-18

Innehållsförteckning

Underliggande anvisningar

1. Inledning

Detta dokument är en övergripande beskrivning av tillämpliga RIV Tekniska Anvisningar för den som ska utveckla webservices som baserar sig på SOAP.

Open

Anvisningen i sitt sammanhang

1.1 Målgrupp

Dokumentet riktar sig till aktörer som vill få en grundlig förståelse RIV Tekniska anvisningar samt för motiven bakom dessa och därigenom vad som kan förväntas av de tekniska profiler och anvisningar som utarbetats för SOAP-protokollet.

1.2 Syfte

Dokumentet syftar till att beskriva hur man realiserar utbytet av information mellan två parter baserat på XML/WSDL-baserade integrationsprofiler enligt SOA över SOAP.

1.3 Tillgänglighet

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

2. Terminologi

Detta avsnitt beskriver termer som används genomgående i denna och tillhörande anvisningar.

2.1 Termer och symboler för utbyte av meddelande

Följande termer används för att beskriva grundläggande utbyte av meddelanden:

2.1.1 Meddelande

Informationsmängd som förpackats av en avsändare i syfte att överföra strukturerad information till en mottagare. Meddelandets tekniska inramning benämns meddelandekuvert. Kuvertet omsluter ett meddelandehuvud och ett meddelandeinnehåll. Inom ramen för nationella tjänstekontrakt enligt RIV tekniska anvisningar tillämpas standarden SOAP 1.1, vars motsvarande begrepp är Envelope, Header och Body. I anvisningen används de svenska termerna och motsvarande termer ur SOAP-standarden växelvis beroende på sammanhang.

Följande figur illustrerar den generella uppbyggnaden av ett meddelande:

2.1.2 Avsändare

Tjänstekomponent som sänder ett meddelande till en mottagare.

2.1.3 Mottagare

Tjänstekomponent som tar emot ett meddelande från en avsändare.

2.2 Termer och symboler för tjänsteinteraktioner

Följande termer definierar tjänsteinteraktioner och deras byggstenar:

2.2.1 Tjänsteinteraktion

Samverkan mellan två parter enligt någon av interaktionstyperna Fråga-Svar, Informationsspridning och Uppdrag-Resultat. Parterna är abstrakta och benämns generellt "Initiativtagare" och "Utförare" (jmfr WS-BPEL "Initiator", "Responder"). En tjänsteinteraktion avser den tjänst som utföraren tillhandahåller enligt definitionen av ett tjänstekontrakt.

Interaktionstyperna Fråga-Svar och Informationsspridning beskriver meddelandeutbytet enligt det tjänstekontrakt som utförarens tjänst är realiserad på.

Interaktionstypen Uppdrag-Resultat definierar ett bilateralt utbyte mellan parterna. Initiativtagaren ger utföraren ett uppdrag genom att anropa dess tjänst. Utföraren genomför uppdraget och avslutar interaktionen genom att anropa den ursprungligna initiativtagarens tjänst i syfte att delge resultatet. Här sker alltså rent tekniskt ett byte av roll mellan utförare och initiativtagare. I tjänsteinteraktioner av denna typ definierar båda parterna en tjänst var och dessa har ofta olika utformning.

Tekniskt sett beskrivs en tjänsteinteraktion som en WSDL med beroende till ett eller ett par tjänstescheman (beroende på typ).

Följande uppställning beskriver hur de olika tjänsteinteraktionstyperna visualiseras i anvisningarna:

2.2.2 Övriga termer

För beskrivning av allmänna termer se RIV Tekniska Anvisningar Översikt.

Vissa termer har nedan en kontextuell beskrivning för området som komplement till beskrivningen i översikten

3. Interoperabilitet via SOAP Webservices

RIV Tekniska anvisningar SOAP Webservices bygger i stor utsträckning på väl etablerade standarder för web services som getts ut av Web Services Interoperability Organization (WS-I) Dessa ger en försäkran om att underliggande standarder, specifikationer och rekommendationer från erkända standardiseringsorgan som exempelvis Internet Engineering Task Force (IETF), World Wide Web Consortium (W3C) och Organization for the Advancement of Structured Information Standards (OASIS) används på ett sätt som fungerar tillsammans.

RIV Tekniska anvisningars RIV-profiler konstrueras som tilläggsprofiler till de interoperabilitetsprofiler för web-services som definieras av WS-I.

Profiler byggs upp stegvis med bas i WS-I Basic Profile. Påbyggnadsprofil följer, baserat på WS-I Basic Security Profile och i efterföljande steg på WS-I Secure Reliable Conversation Profile.

För mer information om WS-I profiler och deras ingående specifikationer hänvisas till WS-I Deliverables

3.1 Leverantörsspecifika avvikelser och konventioner

RIV-profiler ska ta rimlig hänsyn till leverantörsspecifika konventioner och ev. brister i följsamhet mot WS-I:s profiler för att uppnå praktisk interoperabilitet. Detta gäller framför allt aktuella versioner av Microsoft Windows Communication Foundation och Java-plattformens motsvarighet JAX-WS.

3.2 Versionshantering

Anvisning för Tjänsteschema definierar regler för uppbyggnad av meddelanden för tjänsternas operationer med syfte att styra in mot utbyggbarhet och interoperabilitet. Detta innebär design och namnrymdshantering för att klara krav på framåt- och bakåtkompatibilitet med utgångspunkt i hur XML hanteras i utvecklingsverktyg. Namnrymder ska också tydliggöra när ett nytt schema definierar en ny version (utan bakåtkompatibilitet) i förhållande till en tidigare version. Utgångspunkten är att det behövs strategier för att minska behovet av nya versioner (genom bakåt/framåt-kompatibilitet), men samtidigt tydliggöra regler för uttag av nya versioner då det inte är möjligt eller ändamålsenligt med bevarad kompatibilitet

Principlösningen är anpassad för att fungera med utvecklingsverktyg med ansatsen att generera källkod utgående från tjänstekontrakt beskrivna med hjälp av WSDL och XML Scheman.

Den valda strategin för versionshantering är baserad på ett arbete av W3C som beskriver och värderar en uppsättning strategier. Den strategi som tillämpas i RIV Tekniska Anvisningar beskrivs här: W3C-Extending and Versioning Languages: XML Languages .

Konsekvensen av strategin är en uppsättning detaljerade krav. Dessa beskrivs nedan.    

3.3 Notation för att ange version

Versionsnummer sätts på ett tjänstekontrakt enligt formatet: major.minor

För nya kompatibla versioner av ett tjänstekontrakt behålls major-siffran medan minor-siffran stegas upp ett steg, t ex från 1.0 till 1.1.

För nya icke kompatibla versioner stegas major-siffran upp och minor-siffran sätts tillbaka till 0, t ex från 1.1 till 2.0.

För att beskriva att ett meddelande innehåller element från en viss version av ett tjänstekontrakt (v1.0 i exemplet nedan) används följande notation:

Anm. "e1.0" anger element från v1.0 av tjänsteschemat

För att beskriva att ett meddelande som innehåller element från flera olika versioner av ett tjänstekontrakt (v1.0 och v1.1 i exemplet nedan) används följande notation:

Anm. I bilden förstärks att element från v1.1 av tjänstekontraktet har tillförts meddelandet

En initiativtagare byggd för v1.0 av ett tjänstekontrakt visualiseras enligt:

En utförare byggd för v1.0 av ett tjänsteschema visualiseras enligt:

3.4 Bakåt- och framåtkompatibilitet

Bakåtkompatibilitet innebär att en avsändare kan skicka meddelande till en mottagare där meddelandet följer en äldre version av tjänstekontraktet än vad mottagare är baserad på. Detta kräver att mottagaren kan behandla meddelanden av den äldre versionen trots att dessa saknar de nya elementen. Bakåtkompatibilitet illustreras med hjälp av följande bild:

Framåtkompatibilitet innebär att en avsändare kan skicka meddelande till en mottagare där meddelandet följer en nyare version av tjänstekontraktet än vad mottagaren är baserad på. Detta kräver att mottagaren kan bortse från informationen som tillförts i den nyare versionen av meddelandet.

3.4.1 Teknisk realisation av bakåt- och framåtkompatibilitet

I praktiken finns det i huvudsak en typ av förändring som uppfyller såväl bakåt- som framåtkompatibilitet: tillägg av nya, icke-obligatoriska element. Tekniskt sett handlar det om att säkerställa att ett meddelande alltid kan valideras mot den version av XML Schemat som befintliga avsändare och mottagare byggdes för. Alltså kan olika avsändare och mottagare ha källkod som är genererad utgående från olika minor-versioner av tjänstekontraktet.

En försvårande omständighet är i detta sammanhang att många verktyg för tolkning och validering av XML tagit fasta på ett krav i specifikationen för XML Schema som benämns "Unique Particle Attribution". Den av W3C beskrivna strategin för versionering tar delvis hänsyn till denna restriktion. Det är en erfarenhetsmässigt påvisad metod för att tekniskt realisera krav på bakåt- och framåtkompatibilitet som bl.a. tillämpas inom OASIS (WS-Policy, WS-Topic m.fl). Valet av strategi medför följande krav på tjänstescheman:

• Versionsdeklaration: Target-namespace skall innehålla major-versionen.

• Namespaces behöver anges för element i instans-dokument: Schema-attributet elementFormDefault skall vara satt till 'qualified' i alla scheman.

• Platshållare för framåtkompatibilitet: Ett xsd:any-element ska finnas som "platshållare" för framtida, icke-obligatoriska element: <xsd:any processContents="lax" minOccurs="0" maxOccurs="unbounded" namespace="##other"/>. Element som introduceras i en ny minor-version läggs i ett separat XML Schema med target-namespace som skiljer sig från major-versionens. Detta är en konsekvens av any-elements deklaration enligt ovan, som tvingar att dessa element ska vara i annan namnrymd.

Utöka nya framåt och bakåtkompatibla versioner av XML Schemat endast med frivilliga element, d.v.s. element som har minOccurs satt till "0".

Se RIV Teknisk anvisning - Tjänsteschema för detaljerade riktlinjer.

3.4.2 Konsekvenser för initiativtagare och utförare

Följande bild illustrerar behov av bakåt och framåtkompatibilitet när initiativtagare använder en äldre version än utföraren:

I detta exempel måste utföraren (v1.1) kunna behandla request-meddelanden av den äldre versionen (v1.0) trots att dessa saknar de nya elementen samt initiativtagaren (v1.0) måste ignorera nya element som kommer i eventuella v1.1-response-meddelanden.

Följande bild illustrerar behov av bakåt och framåtkompatibilitet när initiativtagare använder en nyare version än utföraren:

I detta exempel måste utföraren (v1.0) ignorera nya element som kommer i v1.1-request-meddelanden samt initiativtagaren (v1.1) måste kunna behandla eventuella response-meddelanden av den äldre versionen (v1.0) trots att dessa saknar de nya elementen.

3.5 Icke kompatibla ändringar

När det inte är möjligt eller ändamålsenligt för en ny version av ett tjänstekontrakt att vara kompatibelt med befintlig version så behöver man ta fram en ny huvudversion (major) för tjänstekontraktet. Detta kan innebära att tjänsteproducenter och tjänstekonsumenter behöver ha stöd för flera samtidiga huvudversioner. Se RIV Tekniska Anvisningar Livscykelhantering för tjänstekontrakt samt RIV Tekniska Anvisningar - Parallella huvudversioner av ett tjänstekontrakt för mer detaljer kring detta.

3.6 Införande av ny version av RIV-profiler

Vid användning av en ny icke bakåtkompatibel version av en RIV-profil måste tjänstekontraktet uppgraderas till en ny huvudversion.

4. Namnstandard

RIV Tekniska Anvisningar ska underlätta utveckling och tolkning av WSDL och tjänstescheman genom att föreslå en namnstandard. Namnstandarden ska bäras av de begrepp som ligger till grund för denna anvisning. Namnstandarden ska uttryckas som regler i de enskilda anvisningarna. I och med att profilerna bygger på varandra, finns de flesta namngivningsregler för WSDL i bas-profilen. Även anvisningen för tjänsteschema definierar namngivningsregler.

5. Relation till T-bokens referensarkitektur

T-boken beskriver en referensarkitektur för samverkan mellan vårdens IT-system. Merparten av de termer och begrepp som används i RIV Tekniska Anvisningar har där sin bakgrund och motivation. Strukturen i RIV Tekniska Anvisningar speglar referensarkitekturen.

Nedan illustreras hur dessa begrepp förhåller sig till tekniska artefakter och vilka anvisningar som styr utformningen av dem. Sambanden redovisas för varje enskild typ av tjänsteinteraktion som definieras av T-bokens referensarkitektur: Fråga-svar, Informationsspridning och Uppdrag-resultat. Tjänsteinteraktionerna återges i form av ett UML klassdiagram och visualiseras med hjälp av UML sekvensdiagram.

5.1 Tjänsteinteraktionstyp Fråga-svar

Exemplet är baserat på fråga-svar vid utbyte av journalinformation. Tjänsteinteraktionen beskrivs av följande UML klassdiagram:

Interaktionen mellan parterna beskrivs av följande UML sekvensdiagram där initiativtagaren gör ett synkront anrop med en fråga till utföraren som returnerar ett svar:

5.2 Tjänsteinteraktionstyp Informationsspridning

Exemplet är baserat på informationsspridning för uppdatering av information om en patient. Tjänsteinteraktionen beskrivs av följande UML klassdiagram:

Interaktionen mellan parterna beskrivs av följande UML sekvensdiagram där initiativtagaren (dvs informationsspridaren) gör ett anrop till utföraren (mottagaren av informationen):

5.3 Tjänsteinteraktionstyp Uppdrag-resultat

Exemplet är baserat på en generisk begäran om bearbetning av patientinformation och önskan om ett resultatmeddelande när bearbetningen är klar. Notera att interaktionstypen uppdrag-resultat består av två olika tjänster. Initiativtagaren ger ett uppdrag till utföraren genom att anropa utförarens tjänst. Utföraren utför uppdraget och anropar därefter den ursprungliga initiativtagarens tjänst för att leverera resultatet.

Tjänsteinteraktionen beskrivs av följande UML klassdiagram:

Interaktionen mellan parterna beskrivs av följande UML sekvensdiagram där initiativtagaren (det vill säga beställaren) gör ett anrop till utföraren och utföraren så småningom återkommer genom att göra ett anrop till initiativtagaren (beställaren) :