Jämförda versioner

Gammal version 1

changes.mady.by.user Ranjdar Fallyih

Sparat den

jämfört med

Ny version 2

changes.mady.by.user Ranjdar Fallyih

Sparat den

Nyckel

  • Dessa rader lades till.
  • Denna rad togs bort.
  • Formateringen ändrades.











 

 

 

 

 

 

 

 

 

 


RIV Tekniska Anvisningar Tjänsteschema

Version 2.1.4

ARK_0005

2016-09-27

 

 

 

 

 





Innehållsförteckning


Utgåvehistorik


 

Utgåva

Revision Datum

Beskrivning

Ändringarna gjorda av

Definitiv revision fastställd av

PA1

2011-04-27

Upprättat dokumentet baserat på version 2.0. Uppdaterat dokument för begärda ändringar enligt följande trackers på Osor: 15115.

Marcus.krantz@callistaenterprise.se

 



A

2011-10-19

Revision fastställd

 


Arkitekturledningens tekniska expertgrupp, Center för eHälsa i samverkan

PC1

2011-12-16

Uppdateringar med anledning av flytt av projektplats från Osor till Google code. Endast länkar under rubriken Referenser uppdaterade

hans.thunberg@callistaenterprise.se

 


C

2012-01-03

Revision fastställd

 


Arkitekturledningens tekniska expertgrupp, Center för eHälsa i samverkan

D

2013-06-27

Ny version efter CeHis AR nya processer

CeHis AR T

CeHis AR t

2.1.1

2014-08-20

Förtydligat regel #9 och flyttat XML-exempel till bilaga.

Mattias Nordvall, Inera

 


2.1.1

2014-09-26

Lagt upp iinera mall och publicerat

Lennart Eriksson

 


2.1.2

2014-10-03

Rättat detaljer i bilaga 1.

Mattias Nordvall, Inera

 


2.1.3

2015-12-17

Uppdaterat länkar i referenstabell

Mattias Nordvall, Inera

 


2.1.4

2016-09-27

Läsande tjänster ska inte returnera logiska fel

Tommy Carlsson, Inera


 

 

 

 




1        Inledning

Detta dokument beskriver regelverket RIV Tekniska Anvisningar Tjänsteschema 2.0.

 



1.1      Målgrupp

Denna anvisning riktar sig till dem som ska specificera XML-scheman för tjänstekontrakt i en nationell tjänsteinteraktion. Anvisningen innehåller endast regeluppsättningen. För bakgrund, motiv, krav samt de principer som ligger till grund för framtagning av reglerna hänvisas till Översikt RIV Tekniska Anvisningar 2.1 [R2]

...

Denna profil är verifieras genom exempelapplikationer. Källkoden [R9] 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

VIT-bokens tekniska arkitektur. Principer för uppbyggnad av den nationella arkitekturen i form av en teknisk referensarkitektur samt användningsfall med ett tekniskt perspektiv på realisering.

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

Inera Arkitektur & Regelverk

[R2]          

RIV Tekniska Anvisningar Översikt 2.1

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

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

Inera Arkitektur & Regelverk

[R3]          

RIV Tekniska Anvisningar Basic Profile 2.1

Exempel på anvisning för profil som pekar ut användningen av denna anvisning för specifikation av meddelandeinnehåll (teknisk del).

http://rivta.se/documents/ARK_0002/

Inera Arkitektur & Regelverk

[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”

http://www.ws-i.org/Profiles/BasicProfile-1.1.html

The Web Services Interoperability Organization och ISO

[R5]          

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.

https://bitbucket.org/rivta-profiles/refapp-rivtabp21-cxf/src/master/rivta-bp21-refapp-schemas/

 


Inera Arkitektur & Regelverk

[R6]          

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.

Java CXF: https://bitbucket.org/rivta-profiles/refapp-rivtabp21-cxf/

.NET WCF: https://bitbucket.org/rivta-profiles/refapp-rivtabp21-wcf

Inera Arkitektur & Regelverk

[R7]          

Beskrivning av ”Venetian Blind”

Dokumentet beskriver det designmönster som tillämpas för XML Schema design i denna anvisning.

Webblänk till hemsidan:

http://www.xfront.com/GlobalVersusLocal.html

Okänd.

[R8]        

 

 

 

 




[R9]          

W3C-rapport om utökningsbara XML-scheman

Beskriver problemställningar och strategier för design av meddelanden som ger bra stöd för versionshantering. Versioneringsstrategin som beskrivs i denna översikt och som tillämpas i RIV Teknisk Anvisning Tjänsteschema är baserad på strategi nr 2 i denna rapport.

Webblänk till rapportens hemsida:  http://www.w3.org/2001/tag/doc/versioning-xml

W3C

 

 

 




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 crm:scheduling
  2. Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex MakeBooking
  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 MakeBooking

...

"Venetian Blind" [R7] skall användas som designmönster för tjänstescheman. Designmönstret Venetian Blind innebär följande: 


  • Den interna strukturen i ett meddelande byggs upp med hjälp av globalt deklarerade typer. Med ”globalt deklarerade” menas deklarationer som görs direkt under schema-elementet.
  • Endast rotelementet är deklarerat som ett globalt element. I web-service-fallet innebär det att request- och response-elementen är globalt deklarerade element medan resten är typer.

...

Exempel: ”MakeBooking” respektive “MakeBookingResponse”

 


Regel #5, namn på typer

Attributet ”name” på element som deklarerar request-typer i tjänsteschemat bör ha ett värde som följer följande regel: ${operation}Type

...

     </xs:restriction>

</xs:simpleType> 


Motiv: För att undvika interoperabilitetsproblem bör man ej använda sig av nationella tecken när man definierar typer som kommer att användas i ett tjänstekontrakt. Ofta uppstår annars fel vid kodgenerering från schemat. 


Regel #11, Best-practice för felhantering

...

    </xs:sequence>

</xs:complexType>

 


<xs:simpleType name="ResultCodeEnum">

...

     </xs:restriction>

</xs:simpleType> 

 



Vid ett tekniskt fel levereras ett generellt undantag (SOAP-Exception). Exempel på felsituationer som rapporteras som tekniskt fel kan vara deadlock i databasen eller följdeffekter av programmeringsfel. Denna information bör loggas av tjänstekonsumenten. Informationen är inte riktad till användaren. Användaren kommer enbart att se ”tekniskt fel – inte detaljinformation. Den riktar sig till systemförvaltaren. 


Vid ett logiskt fel i de uppdaterande tjänsterna levereras resultCode och resultText. Syftet med resultText är att tjänstekonsumenten av tjänsten ska kunna visa upp informationen för användaren. Läsande tjänster ska inte 


resultCode kan vara:

  • OK
    Transaktionen har utförts enligt uppdraget i frågemeddelandet.
  • INFO
    Transaktionen har utförts enligt uppdraget i frågemeddelandet, men det finns ett meddelande som tjänstekonsumenten måste visa upp för invånaren. Exempel på detta kan vara ”kom fastande”.
  • ERROR
    Transaktionen har INTE kunnat utföras enligt uppdrag i frågemeddelandet p.g.a. logiskt fel. Det finns ett meddelande som konsumenten måste visa upp (om tillämpbart, annars t.ex. skrivas i batch-log). Exempel på detta kan vara ”tiden har blivit upptagen av annan patient” (från tjänstedomän Invånarens tidbokning).

 


Läsande tjänster ska inte leverera information om logiska fel, d v s resultCode och resultText.

Motiv: Erfarenheter har visat att felhantering genom egen-definierade fel skapar interoperabilitetsproblem och försvårar hantering i intermediärer.

 


                       

Exempel: Se tjänsteschemat i referensapplikationen.

 


4         Bilaga 1: Exempel på bakåtkompatibel utökning

...

Följande exempel är baserat på en delmängd av tjänsteschemat för exempelapplikationerna. Det visar hur elementet subject_of_care läggs till. För att göra utökningen bakåtkompatibel så ges det nya elementet attributet minOccurs=”0”. Dessutom måste any-elementet tas bort för att uppfylla regeln Unique Particle Attribution. 


Tjänsteschema, ny minorversion: GetAvailableTimeslotsResponder_1.1.xsd

...

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1"  xmlns:m1="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1"> 


<xs:import namespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" schemaLocation="GetAvailableTimeslotsResponder_1.1_ext.xsd" />


    <xs:element name="GetAvailableTimeslots" type="tns:GetAvailableTimeslotsType" />

...

</xs:complexType>

</xs:schema>

 


Utökningsschema med element som tillkommit i 1.1: GetAvailableTimeslotsResponder _1.1_ext.xsd

 


<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">


    <xs:element name="subject_of_care" type="core:SubjectOfCareIdType"/>

 


</xs:schema> 


Vid nästa major-version integreras elementen från mellanliggande utökningsscheman i huvudschemat. Elementen kan nu göras obligatoriska (minOccurs=”1”) om så önskas.

 


Tjänsteschema, ny majorversion GetAvailableTimeslotsResponder _2.0.xsd

 


<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0"> 


  <xs:element name="GetAvailableTimeslots" type="tns:GetAvailableTimeslotsType" />


    <xs:complexType name="GetAvailableTimeslotsType">

...

  </xs:complexType>

</xs:schema>

 


5         Bilaga 2: Exempel på icke-bakåtkompatibel utökning

...

Följande exempel är baserat på en delmängd av tjänsteschemat för exempelapplikationerna. Det visar hur elementet subject_of_care läggs till. Det nya elementet är obligatoriskt (genom attributet minOccurs=”1”), vilket gör utökningen icke-bakåtkompatibel. I gengäld kan any-elementet behållas för framtida bruk.

 


Tjänsteschema, ny minorversion: GetAvailableTimeslotsResponder_1.1.xsd

...

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1"  xmlns:m1="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">

 


<xs:import namespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" schemaLocation="GetAvailableTimeslotsResponder_1.1_ext.xsd" />


    <xs:element name="GetAvailableTimeslots" type="tns:GetAvailableTimeslotsType" />

...

  </xs:complexType>

</xs:schema> 


Utökningsschema med element som tillkommit i 1.1: GetAvailableTimeslotsResponder _1.1_ext.xsd

...


<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">


    <xs:element name="subject_of_care" type="core:SubjectOfCareIdType"/> 


</xs:schema> 


Vid nästa major-version integreras elementen från mellanliggande utökningsscheman i huvudschemat: GetAvailableTimeslotsResponder _2.0.xsd

 


<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">


    <xs:element name="GetAvailableTimeslots" type="tns:GetAvailableTimeslotsType" />


    <xs:complexType name="GetAvailableTimeslotsType">

...

  </xs:complexType>

</xs:schema>

 

 

...