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]
1.2 Syfte
Syftet med denna anvisning är att beskriva designregler och namngivningsregler för interoperabilitet samt riktlinjer för att bygga in stöd för versionshantering i tjänstescheman.
Ett uttalat syfte med tjänstescheman är att de ska kunna användas oberoende av kommunikationsstandard. Många tjänstescheman kommer dock att skapas i syfte att importeras i WSDL-filer. Reglerna för tjänstescheman är därför baserade på WS-Basic Profiles regelverk för s.k. [R4]. Målet med anvisningen är att optimera för interoperabilitet vid användning av web-service-baserade RIV TA-profiler utan att göra tjänstescheman beroende av web-services för transport och kuvertering
Exempel på tjänsteschema som följer denna anvisning finns på RIV-förvaltningens hemsida [R5] tillsamman med exempelapplikationer [R6]
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 [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:
- Tjänstedomänens namn: ${tjänsteDomän}, t ex crm:scheduling
- Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex MakeBooking
- 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 MakeBooking
3 Detaljerade regler
Regel #1, designmönster för tjänstescheman
"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.
Anm. I vissa fall kan även andra element än request och response behöva vara globala, t ex används element-referenser till globala element i importerade scheman för att stödja versioneringsstrategin, se nedan.
Motiv: Interoperabilitet, WS-I Basic Profile
Exempel: Tjänstekontrakten för exempelapplikationerna [R5]
Regel #2, namn på xsd-filen
Schema-filen för ett tjänstekontrat bör namnges enligt följande regel: ${tjänsteInteraktion}${roll}_${m.n}.xsd
Motiv: Att ha med versionsnummer i namnet på källkodsfiler är generellt sett något man försöker undvika då det försvårar användning av versionshanteringsverktyg (t ex Subversion, Microsoft Visual Studio). I fallet med tjänsteschema behöver man dock kunna hantera flera olika versioner samtidigt (i byggsystem mm) och för att underlätta den hanteringen ingår versionsnumret i filnamnet på tjänstekontrakt.
Anm. Detta gäller principiellt sett också de XML Schema som importeras/inkluderas av att tjänsteschema och som beskriver RIV Meddelanden men denna anvisning täcker inte in utformning av dessa XML Scheman, se [R8].
Exempel: MakeBookingResponder_1.0.xsd
Regel #3, namn på target namespace
Attributet targetNamespace på schema-elementet skall ha ett värde som definieras av följande regel: urn:riv:${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m}
Motiv: Användningen av major-version i namnrymden är en av att följa fastslagen versioneringsstrategi [R9]. Att ha en unik namnrymd per tjänstekontrakt (tjänsteinteraktion + roll) är en förutsättning för att följa WS-I Basic Profiles [R4] regel om ”operation signature”. Det också generellt goda förutsättningar för att implementera generella bryggor och tjänsteväxlar
Exempel: urn:riv:crm:scheduling:MakeBookingResponder:1
Regel #4, namn på element
Attributet ”name” på element som deklarerar request-element i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}, t ex: MakeBooking
Attributet ”name” på element som deklarerar response-element i tjänsteschemat skall ha ett värde som följer följande regel ${operation}Response, t ex: MakeBookingResponse
Motiv: För konsistent namngivning skall element för in-parametrar ha samma namn som operationen.
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
Attributet ”name” på element som deklarerar response-typer i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}ResponseType
Motiv: Enhetlighet.
Exempel: ” MakeBookingType” respektive ” MakeBookingResponseType”
Regel #6, användning av schema-attributen elementFormDefault och attributeFormDefault
Schema-attributen elementFormDefault och attributeFormDefault skall sättas till "qualified" respektive "unqualified".
Motiv: För att versioneringsstrategin skall fungera är det viktigt att alla element i instans-dokument är namespace-qualified. Detta uppnås genom att sätta schema-attributet elementFormDefault till "qualified".
Exempel: Tjänstekontrakten för exempelapplikationerna [R5]
Regel #7, användning av schema-attributet version
Schema-attributet version bör sättas till "m.n"
Motiv: Då namnrymden inte innehåller minor-version, ger detta en dokumentation som följer intentionen med attributet.
Exempel: <schema ... version="1.0>
Regel #8, användning av any-element för utökningsbarhet
För att uppnå framåtkompatibilitet skall ett xsd:any element läggas in sist i alla komplexa typer som ska kunna utökas, exempel:
Motiv: För att uppnå framåtkompatibilitet måste man "förbereda" sina XML scheman för framtida utökningsbarhet. Detta är en del av den tillämpade strategin för versionering [R9].
Exempel:
<xs:complexType name="SomeType">
<xs:sequence>
<xs:element name="someElement" type="xsd:string" />
<xs:element name="someOtherElement" type="xsd:int" />
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
</xs:sequence>
</xs:complexType>
Regel #9, nya element i utökningsschema
För att skapa en ny minor-version av ett tjänsteschema, skall följande regler följas:
- De nya elementen läggs till i befintligt schema närmast före any-elementet i den komplexa typ som ska utökas. Dessa nya element har ingen typ, utan refererar (xsd:ref=”…”) element som är rotelement i en ny schema-fil (utöknings-schema)
- För att ändringen ska vara bakåtkompatibel så måste de nya elementen ha attributet minoccurs=”0”. Det leder i sin tur att any-elementet måste tas bort. Detta för att uppfylla kravet på Unique Particle Attribution i Xml Schema 1.0. Följden blir att denna komplexa typ inte kan förändras fler gånger på ett bakåtkompatibelt sätt.
- De nya elementen definieras i en ny schema-fil (utökningsschema) med ett namn som följer följande regel: ${tjänsteInteraktion}${roll}_${m.n}_ext.xsd
- Utökningsschemat ska ha en targetNamespace enligt följande regel: urn:riv:${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m.n}
- Tjänsteschemat importerar (xsd:import) utöknings-schemat som ges namnrymdsalias enligt följande regel: m${n}
- Tjänsteschemats versionsattribut ändras till den nya minor-versionen.
- I nästa major-version av tjänsteschemat flyttas element-deklarationerna in från alla utökningsscheman (det finns ett för varje minor-version som tilkommit sedan förra major-versionen skapades). Dessutom läggs eventuellt borttagna any-element tillbaka, enligt regel #8.
Motiv: Detta förfarande är en konsekvens av vald strategi för versionering [R9]. Se [R2] för ytterligare bakgrund.
Se även bilaga 1 och 2 för exempel på utökningar.
Regel #10 Nationella tecken
Tjänstescheman ska undvika att använda nationella tecken i såväl elementnamn, attributnamn som vid listning av värdemämngder för uppräkningstyper. Följande exempel bör därför undvikas:
<xs:simpleType name=”Å”>
<xs:annotation>
<xs:documentation>…</xs:documentation>
</xs:annotation>
<xs:restriction base=”xs:string”>
<xs:enumeration value=”Återställas helt” />
<xs:enumeration value=”Återställas delvis” />
<xs:enumeration value=”Det går inte att bedöma” />
</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
Ett tjänstekontrakt ska inte definiera några egna fel (SOAP-exceptions). Istället bör följande struktur för felhantering tillämpas i svarsmeddelandet (för fråga-svar):
<xs:complexType name="MakeBookingResponseType">
<xs:sequence>
<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />
<xs:element name="resultCode" type="tns:ResultCodeEnum" minOccurs="1" maxOccurs="1" />
<xs:element name="resultText" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ResultCodeEnum">
<xs:restriction base="xs:string">
<xs:enumeration value="OK"/>
<xs:enumeration value="ERROR"/>
<xs:enumeration value="INFO"/>
</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
<?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" 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 name="GetAvailableTimeslotsType">
<xs:sequence>
<xs:element name="healthcare_facility" type="core:HsaIdType" minOccurs="1" maxOccurs="1" />
<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />
<xs:element name="startDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="endDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="performer" type="core:HsaIdType" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="timeTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="timeTypeID" type="core:TimeTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="careTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="careTypeID" type="core:CareTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element ref="m1:subject_of_care" minOccurs="0"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</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:sequence>
<xs:element name="healthcare_facility" type="core:HsaIdType" minOccurs="1" maxOccurs="1" />
<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />
<xs:element name="startDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="endDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="performer" type="core:HsaIdType" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="timeTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="timeTypeID" type="core:TimeTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="careTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="careTypeID" type="core:CareTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="subject_of_care" type=”subject_of_care” minOccurs="1"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</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
<?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" 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 name="GetAvailableTimeslotsType">
<xs:sequence>
<xs:element name="healthcare_facility" type="core:HsaIdType" minOccurs="1" maxOccurs="1" />
<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />
<xs:element name="startDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="endDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="performer" type="core:HsaIdType" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="timeTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="timeTypeID" type="core:TimeTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="careTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="careTypeID" type="core:CareTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element ref="m1:subject_of_care" minOccurs="1"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</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:sequence>
<xs:element name="healthcare_facility" type="core:HsaIdType" minOccurs="1" maxOccurs="1" />
<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />
<xs:element name="startDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="endDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />
<xs:element name="performer" type="core:HsaIdType" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="timeTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="timeTypeID" type="core:TimeTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="careTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />
<xs:element name="careTypeID" type="core:CareTypeIDType" minOccurs="0" maxOccurs="1" />
<xs:element name="subject_of_care" type=”subject_of_care” minOccurs="1"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
...
RIV Tekniska Anvisningar TjänsteschemaVersion 2.1.11 ARK_0005 2021-11-24 |
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 | |
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 | |
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 | |
2.1.5 | 2018-05-08 | Lagt till att även domänprefix kan ha olika värden, var förut hårt satt till "riv:" Förtydligat namnsättningsregler och struktur för domän resp interaktionsnivå Uppdaterat regel #7 från bör till skall | Björn Hedman, Inera | |
2.1.6 | 2019-12-18 | Uppdaterat regel #11 till att tydligare definiera hur felhantering och återrapportering skall ske. Specificerar användandet av SOAP Faults samt tydliggör hantering av ResultCode och ResultText | Anders Malmros, Inera | |
2.1.7 | 2019-12-19 | Förtydligat hur hantering av minor uppdateringar ska ske regel 2, namsättning fil ändrat kapitel med exempel till att hänsvisa till bilagor | Björn Hedman, Inera | |
2.1.8 | 2020-09-24 | Flyttat ut exempel på utökning av schemat till Bilaga, förtydligat att ANY-elementet kan bytas ut mot enbart ett element, rättat domän-prefix och små punkterings och skrivfel. | Ranjdar Fallyih, Thomas Siltberg, Claudia Ehrentraut (Inera) | |
2.1.9 | 2021-09-09 | Obsoleta mailadresser borttagna ur revisionshistoriken. Ersatta med namn | Anders Malmros | |
2.1.10 | 2021-09-14 | Uppdaterat regel #11 avseende ett exempel på ett soap faults detail-fält då detta var fel formaterat | Anders Malmros | |
2.1.11 | 2021-11-24 | Ingen uppdatering. Vill endast komplettera i versionshistoriken att anvisningen sedan v 2.1.6 tillåter läsande tjänster att returnera logiska fel. | Anders Malmros |
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]
1.2 Syfte
Syftet med denna anvisning är att beskriva designregler och namngivningsregler för interoperabilitet samt riktlinjer för att bygga in stöd för versionshantering i tjänstescheman.
Ett uttalat syfte med tjänstescheman är att de ska kunna användas oberoende av kommunikationsstandard. Många tjänstescheman kommer dock att skapas i syfte att importeras i WSDL-filer. Reglerna för tjänstescheman är därför baserade på WS-Basic Profiles regelverk för s.k. [R4]. Målet med anvisningen är att optimera för interoperabilitet vid användning av web-service-baserade RIV TA-profiler utan att göra tjänstescheman beroende av web-services för transport och kuvertering
Exempel på tjänsteschema som följer denna anvisning finns på RIV-förvaltningens hemsida [R5] tillsamman med exempelapplikationer [R6]
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 [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. | 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. | 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). | 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” | 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: | 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:
- Tjänstedomänens prefix: ${domänPrefix}, t ex riv eller riv-application
- Tjänstedomänens namn: ${tjänsteDomän}, t ex clinicalprocess:activity:request
- Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex GetRequest
- 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 MakeBooking
3 Detaljerade regler
Regel #1, designmönster för tjänstescheman
"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.
Anm. I vissa fall kan även andra element än request och response behöva vara globala, t ex används element-referenser till globala element i importerade scheman för att stödja versioneringsstrategin, se nedan.
Motiv: Interoperabilitet, WS-I Basic Profile
Exempel: Tjänstekontrakten för exempelapplikationerna [R5]
Regel #2, namn på xsd-filen
Schema-filen för ett tjänstekontrat bör namnges enligt följande regel: ${tjänsteInteraktion}${roll}_${m.n}.xsd
Observera utökningsscheman namnsätts enligt ${tjänsteInteraktion}${roll}_${m.n}_ext.xsd
Motiv: Att ha med versionsnummer i namnet på källkodsfiler är generellt sett något man försöker undvika då det försvårar användning av versionshanteringsverktyg (t ex Subversion, Microsoft Visual Studio). I fallet med tjänsteschema behöver man dock kunna hantera flera olika versioner samtidigt (i byggsystem mm) och för att underlätta den hanteringen ingår versionsnumret i filnamnet på tjänstekontrakt.
Anm. Detta gäller principiellt sett också de XML Schema som importeras/inkluderas av att tjänsteschema och som beskriver RIV Meddelanden men denna anvisning täcker inte in utformning av dessa XML Scheman, se [R8].
Exempel: MakeBookingResponder_1.0.xsd
Version i filnamnet: Versionen i filnamnet ska återspegla interaktionens logiska version och räknas alltså bara upp om strukturen för interaktionen förändras, övriga förändringar som sker rent tekniskt i filen påverkar inte versionen.
Om ett gemensamt schema har förändrats och bytt version och därigenom filnamn så behöver importen av detta i interaktionsschemat uppdateras men om inga objekt i interaktionen påverkas så behöver inte interaktionens version lyftas
Se även Bilaga1 "Exempel på utökning av tjänsteschema"
Underordnade sidor (visning av underordnade) |
---|
Regel #3, namn på target namespace
Attributet targetNamespace på schema-elementet för en tjänsteinteraktion skall ha ett värde som definieras av följande regel: urn:${domänPrefix}:${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m}
(Reglerna för namnsättning av domänprefix och tjänstedomän finns mer utförligt beskrivna i dokumentet Domännamnsättning)
Motiv:
Användningen av major-version i namnrymden är en av att följa fastslagen versioneringsstrategi [R9]. Att ha en unik namnrymd per tjänstekontrakt (tjänsteinteraktion + roll) är en förutsättning för att följa WS-I Basic Profiles [R4] regel om ”operation signature”. Det också generellt goda förutsättningar för att implementera generella bryggor och tjänsteväxlar
Exempel:
Nationell domän
urn:riv:crm:scheduling:MakeBookingResponder:1
Regel #4, namn på element
Attributet ”name” på element som deklarerar request-element i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}, t ex: MakeBooking
Attributet ”name” på element som deklarerar response-element i tjänsteschemat skall ha ett värde som följer följande regel ${operation}Response, t ex: MakeBookingResponse
Motiv: För konsistent namngivning skall element för in-parametrar ha samma namn som operationen.
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
Attributet ”name” på element som deklarerar response-typer i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}ResponseType
Motiv: Enhetlighet.
Exempel: ” MakeBookingType” respektive ” MakeBookingResponseType”
Regel #6, användning av schema-attributen elementFormDefault och attributeFormDefault
Schema-attributen elementFormDefault och attributeFormDefault skall sättas till "qualified" respektive "unqualified".
Motiv: För att versioneringsstrategin skall fungera är det viktigt att alla element i instans-dokument är namespace-qualified. Detta uppnås genom att sätta schema-attributet elementFormDefault till "qualified".
Exempel: Tjänstekontrakten för exempelapplikationerna [R5]
Regel #7, användning av schema-attributet version
Schema-attributet version skall sättas till "m.n"
Motiv: Då namnrymden inte innehåller minor-version, ger detta en dokumentation som följer intentionen med attributet.
Exempel: <schema ... version="1.0>
Regel #8, användning av any-element för utökningsbarhet
För att uppnå framåtkompatibilitet skall ett xsd:any element läggas in sist i alla komplexa typer som ska kunna utökas.
Motiv: För att uppnå framåtkompatibilitet måste man "förbereda" sina XML scheman för framtida utökningsbarhet. Detta är en del av den tillämpade strategin för versionering [R9].
Exempel:
<xs:complexType name="SomeType">
<xs:sequence>
<xs:element name="someElement" type="xsd:string" />
<xs:element name="someOtherElement" type="xsd:int" />
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
</xs:sequence>
</xs:complexType>
Regel #9, nya element i utökningsschema
För att lägga till nya element och skapa en ny minor-version av ett tjänsteschema, skall följande regler följas:
- Det nya elementet läggs till i befintligt schema närmast före any-elementet i den komplexa typ som ska utökas. Detta nya element har ingen typ, utan refererar (xsd:ref=”…”) element som är rotelement i en ny schema-fil (utöknings-schema)
- Exempel <xs:elementref="m1:financingOrganization"minOccurs="0"maxOccurs="unbounded"/>
- För att ändringen ska vara bakåtkompatibel så måste det nya elementet ha attributet minoccurs=”0”. Det leder i sin tur att any-elementet måste tas bort. Detta för att uppfylla kravet på Unique Particle Attribution i Xml Schema 1.0. Följden blir att denna komplexa typ inte kan förändras fler gånger på ett bakåtkompatibelt sätt.
- Det nya elementet definieras i en ny schema-fil (utökningsschema) med ett namn som följer följande regel: ${tjänsteInteraktion}${roll}_${m.n}_ext.xsd
- Utökningsschemat ska ha en targetNamespace enligt följande regel: urn:$(domänPrefix):${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m.n}
- Tjänsteschemat importerar (xsd:import) utöknings-schemat som ges namnrymdsalias enligt följande regel: m${n}
- Exempel: xmlns:m1='urn:riv:infrastructure:directory:organization:GetUnitResponder:2.2'
- Tjänsteschemats versionsattribut ändras till den nya minor-versionen.
- I nästa major-version av tjänsteschemat flyttas element-deklarationerna in från alla utökningsscheman (det finns ett för varje minor-version som tilkommit sedan förra major-versionen skapades). Dessutom läggs eventuellt borttagna any-element tillbaka, enligt regel #8.
Motiv: Detta förfarande är en konsekvens av vald strategi för versionering [R9]. Se [R2] för ytterligare bakgrund.
Se även Bilaga1 "Exempel på utökning av tjänsteschema"
Underordnade sidor (visning av underordnade) |
---|
Regel #10 Nationella tecken
Tjänstescheman ska undvika att använda nationella tecken i såväl elementnamn, attributnamn som vid listning av värdemämngder för uppräkningstyper. Följande exempel bör därför undvikas:
<xs:simpleType name=”Å”>
<xs:annotation>
<xs:documentation>…</xs:documentation>
</xs:annotation>
<xs:restriction base=”xs:string”>
<xs:enumeration value=”Återställas helt” />
<xs:enumeration value=”Återställas delvis” />
<xs:enumeration value=”Det går inte att bedöma” />
</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, Felhantering och återrapportering
Tekniska fel
Tekniska fel återrapporteras till tjänstekonsumenter med HTTP statuskod 500 (serverfel) och ett svarsmeddelande utformat som ett SOAP Fault, så som det definieras av WS-I Basic Profile 2.1.
SOAP-standarden, vilken WS-I bygger på, definierar fyra generella felkoder:
VersionMismatch
MustUnderstand
Client
Server
Ur en tjänsteproducents perspektiv är Client och Server mest intressanta. Faultcode=’soap:Client’ betyder att det är fel på tjänstebegärans innehåll eller dess kontext (exempelvis klientcertifikat eller konsumentens åtkomstbehörighet), och att omsändning inte ska ske utan felkorrigerande åtgärd på konsumentsidan. Faultcode=’soap:Server’ betyder att behandlingen gått fel, men det var inget fel på begäran i sig och omsändning kan ske. För automatiserad omsändningsstrategi rekommenderas ökande omsändningsintervall för att inte belasta nät och producentsystem i onödan.
Det rekommenderas att hålla sig till de generella felkoderna, men om man för ett tjänstekontrakt absolut behöver definiera egna felkoder med finare granularitet, skall dessa definieras i en separat namnrymd. Konsumentens förväntade agerande baserat på dessa felkoder måste finnas tydligt beskrivna i tjänstekontraktsbeskrivningen.
Exempel:
Kodblock | ||
---|---|---|
| ||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:myservice="http://schemas.inera.se/faultcodes/">
<soap:Header/>
<soap:Body>
<soap:Fault>
<faultcode>myservice:Server.connectFailure</faultcode>
<faultstring>Connection to resource failed</faultstring>
<detail><xs:string xmlns:xs="http://www.w3.org/2001/XMLSchema">instance prdtccgmx01 cannot connect to prdtccgmxdb</xs:string></detail>
</soap:Fault>
</soap:Body>
</soap:Envelope> |
Information i SOAP Faults bör loggas av tjänstekonsumenten. Informationen är inte riktad till användaren utan till systemförvaltaren. Användaren ska endast exponeras för ”tekniskt fel” – inte detaljinformationen från SOAP Fault.
Felbeskrivning i fälten faultstring och detail ska innehålla tillräcklig information för att driva felsökningen framåt. Om det till exempel finns identifieringsbegrepp eller loggid som kan underlätta felsökning skall dessa inkluderas.
Fältet faultactor kan användas i enighet med SOAP-standarden, men dess utformning och användning definieras ej av RIVTA utöver SOAP-standardens riktlinjer.
Exempel:
Kodblock | ||
---|---|---|
| ||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header/>
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Ursprunglig tjänstekonsument SE2321000016-93GN beviljades ej åtkomst till SE2321000016-6RK5 med GetClinicalChemistryLabOrderOutcome</faultstring>
<faultactor>http://rtp.sll.se</faultactor>
</soap:Fault>
</soap:Body>
</soap:Envelope> |
Logiska fel och återrapportering
För logiska fel och återrapportering av status kan svar inkludera elementen resultCode och resultText. ResultCode kan endast ha värdena OK, INFO eller ERROR enligt följande:
Kodblock | ||
---|---|---|
| ||
<xs:complexType name="X">
<xs:sequence>
...
<xs:element name="resultCode" type="tns:ResultCodeEnum" minOccurs="1" maxOccurs="1" />
<xs:element name="resultText" type="xs:string" minOccurs="0" maxOccurs="1" />
...
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ResultCodeEnum">
<xs:restriction base="xs:string">
<xs:enumeration value="OK"/>
<xs:enumeration value="ERROR"/>
<xs:enumeration value="INFO"/>
</xs:restriction>
</xs:simpleType> |
Logiskt fel
Ett logisk fel är en situation där behandlingen kan ha resulterat i ett, ur slutanvändarens perspektiv, oväntat utfall. För att klassas som ett logiskt fel måste tjänstebegäran utformats enligt överenskommelse (korrekt enligt XML-schema och tjänstekontraktsbeskrivning) och tjänsteproducentens behandling har inte misslyckats på grund av ett tekniskt fel hos vare sig tjänstekonsument eller tjänsteproducent enligt definitionen ovan.
För återrapportering av logiska fel ska svaret innehålla ett element “resultCode” med värde ERROR och en textuell felbeskrivning av felet i element “resultText”.
ResultText skall loggas och kan visas upp för användaren i de fall då det är tillämpbart.
Exempel:
Kodblock | ||
---|---|---|
| ||
<MakeBookingResponse>
<resultCode>ERROR</resultCode>
<resultText>Tiden var redan bokad och därför misslyckades denna bokning</resultText>
</MakeBookingResponse> |
Återrapportering
Inget att rapportera
Om man inte har något speciellt att rapportera kring behandling av en tjänstebegäran kan man i svaret ändå inkludera elementet “resultCode” med värde OK och utelämna elementet “resultText”.
Exempel:
Kodblock | ||
---|---|---|
| ||
<MakeBookingResponse>
<bookingId>45674567</bookingId>
<resultCode>OK</resultCode>
</MakeBookingResponse> |
Meddelande till systemförvaltare
Om man efter lyckad behandling av en tjänstebegäran vill återrapportera information från behandlingen eller beskrivande text för returnerad data ska man i svaret inkludera elementet “resultCode” med värde OK och elementet “resultText” innehållande den text som ska loggas men inte visas för användaren.
Exempel:
Kodblock | ||
---|---|---|
| ||
<GetAvailableDatesResponse>
<resultCode>OK</resultCode>
<resultText>No times ever returned for today's date</resultText>
</GetAvailableDatesResponse> |
Meddelande till användare
Om man efter lyckad behandling av en tjänstebegäran vill återrapportera ett meddelande som skall visas upp för användaren ska man i svaret inkludera elementet “resultCode” med värde INFO och elementet “resultText” innehållande meddelandet som ska visas upp.
Exempel:
Kodblock | ||
---|---|---|
| ||
<GetAvailableDateResponse>
<bookingId>4566320</bookingId>
<resultCode>INFO</resultCode>
<resultText>Inga svar då medgivande att lämna ut data saknades för denna patient</resultText>
</GetAvailableDateResponse> |