...
UTF-8 is voor XML de meest gangbare Unicode-encoding. Encoding wordt aangegeven in een XML-prolog:
| Code Block |
|---|
<?xml version="1.0" encoding="utf-8"?> |
Berichten worden uitgewisseld en gelogd in UTF-8 encoding.
...
Hieronder staat een voorbeeld van een HL7v3-bericht dat is verpakt in een SOAP Envelope. Het betreft een opvraag van medicatieverstrekkingen. De voorbeelden in dit document gaan uit van een opvraag met behulp van een zorgtoepassing specifieke interactie. De opbouw van een generieke interactie is in grote lijnen hetzelfde. Eventuele afwijkingen ten opzichte van de voorbeelden worden in het hoofdstuk besproken.
| Code Block |
|---|
<?xml version="1.0" encoding="utf-8"?> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
<QURX_IN990111NL xmlns="urn:hl7-org:v3"> |
<id extension="0032616767" root="2.16.840.1.113883.2.4.6.2.451.12.21"/> |
<creationTime value="20040910170245"/> |
... andere elementen van de Transmission Wrapper... |
<ControlActProcess moodCode="EVN"> |
<QueryByParameterPayload> |
</QueryByParameterPayload> |
|
Het voorbeeld is hieronder in stukken geknipt en van commentaar voorzien.
...
De prolog met UTF-8 declaratie.
| Code Block |
|---|
<?xml version="1.0" encoding="utf-8"?> |
|
SOAP Envelope met daarin namespace declaraties.
| Code Block |
|---|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
|
SOAP Body met daarin het omsluitende element van de opvraging van medicatieverstrekkingen. Omdat dit element de HL7v3-namespace tot default namespace maakt, maken alle elementen daarin automatisch deel uit van de HL7v3-namespace.
...
| Code Block |
|---|
<soapenv:Body> |
...
<QURX_IN990111NL xmlns="urn:hl7-org:v3"> |
Elementen uit de Transmission Wrapper van HL7v3.
| Code Block |
|---|
<id extension="0032616767" root="2.16.840.1.113883.2.4.6.2.451.12.21"/> |
<creationTime value="20040910170245"/> |
... andere elementen van de Transmission Wrapper... |
|
De Control Act Wrapper.
...
| Code Block |
|---|
<ControlActProcess moodCode="RQO"> |
|
Het feitelijke bericht, een opvraging naar medicatie van een bepaald PatientId.
<QueryByParameterPayload> . | Code Block |
|---|
<QueryByParameterPayload>
... verdere inhoud ... |
</QueryByParameterPayload> |
|
Afsluiting van de onderdelen.
Er zijn verschillende soorten SOAP Headers mogelijk. De beveiliging implementatiehandleidingen [IH BA DigiD]
[IH BA PKIO-pas][IH BA Transactietoken][IH BA Mandaattoken][IH BA Inschrijftoken] [IH tokens generiek] beschrijven deze headers. Deze paragraaf beschrijft de mogelijke attributen van SOAP-headers.
...
Het attribuut soap:actor geeft aan welke "actor" een bepaalde header moet verwerken. Met de soap:actor wordt in AORTA een functie aangegeven: bijvoorbeeld de ZIM of het GBx dat als eindbestemming dient. De soap:actor geeft in AORTA dus geen adres van een specifiek GBx.
| Code Block |
|---|
<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> |
"http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" |
soap:actor="http://www.aortarelease.nl/actor/gbx" soap:mustUnderstand="1"> |
|
Voor de headers voor tokenauthenticatie en andere headers gericht aan de ZIM wordt aangeraden de waarde http://www.aortarelease.nl/actor/zim te gebruiken. Voor headers gericht op een GBx is de waarde http://www.aortarelease.nl/actor/gbx verplicht.
| Code Block |
|---|
<ao:authenticationTokens ... soap:actor="http://www.aortarelease.nl/actor/zim"> |
<wss:Security ... soap:actor="http://www.aortarelease.nl/actor/gbx"> |
|
Andere waarden voor actor zijn niet toegestaan. De ZIM dient een header gericht aan een GBx ongewijzigd door te geven aan het GBx van bestemming.
...
SOAP 1.1 definieert een binding op HTTP waarbij SOAP requests en responses met HTTP POST worden uitgewisseld. Daarbij wordt het SOAP request als HTTP request met de method POST verzonden naar een server, die (behoudens fouten) een SOAP response, verpakt in een HTTP response, terugzendt als antwoord op de POST. Hieronder een voorbeeld van een SOAP request – response over HTTP. Dit voorbeeld is gebaseerd op het volgende interactiediagram, een fragment van “medicatieverstrekkingen opvragen”.
Image Added
Figuur 6 – Interactiediagram “medicatieverstrekkingen opvragen”
...
Hieronder het verzoek, dus zowel het HTTP als het SOAP request, als de HL7v3-interactie QURX_IN990111NL (Medication Dispense List Query).
| Code Block |
|---|
POST /VerstrekkingsLijstquery HTTP/1.1 |
SOAPAction: "urn:hl7-org:v3/VerstrekkingsLijstquery_QueryResponse" |
Content-Type: text/xml; charset=UTF-8 |
<?xml version="1.0" encoding="utf-8"?> |
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> |
<QURX_IN990111NL xmlns="urn:hl7-org:v3"> |
|
Eerst wordt de HTTP methode genoemd (POST), en de versie, dan volgen een aantal headers met HTTP gegevens. SOAP 1.1 verplicht het noemen van "text/xml" als Content-Type.
...
Hieronder een voorbeeld van de HTTP response op de POST methode. Dit is tevens de SOAP response, en de HL7v3-interactie QURX_IN990113NL (Medication Dispense List Query Response):
| Code Block |
|---|
HTTP/1.1 200 OK |
Content-Type: text/xml;charset=utf-8 |
Date: Wed, 03 Feb 2010 12:59:18 GMT |
Server: Apache-Coyote/1.1 |
<?xml version="1.0" encoding="utf-8"?> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
<QURX_IN990113NL xmlns="urn:hl7-org:v3"> |
|
Eerst wordt de HTTP-versie aangegeven en de status (200 OK). Vervolgens weer enige HTTP Headers en dan de SOAP Envelope.
...
SOAP kent een Fault element dat onderdeel is van de SOAP Body en daar maar één keer mag voorkomen. Het SOAP Fault element heeft vier subelementen, hieronder kort toegelicht.
faultcode
Een verplicht element. De waarde van dit element moet namespace gekwalificeerd zijn. SOAP kent zelf vier foutcodes die verderop in deze paragraaf genoemd worden.
faultstring
Een verplicht element die een voor mensen leesbare uitleg bevat over de aard van de opgetreden fout.
faultactor
Dit element is bedoeld om informatie te geven over wie de fout gegenereerd heeft. Het lijkt op het SOAP actor attribuut, maar geeft de bron van de fout aan in plaats van het einddoel van de header. Applicaties die niet het eindpunt (ultimate destination) zijn van het SOAP bericht, moeten het faultactor element opnemen. Applicaties die wel het einddoel zijn, mogen het faultactor element opnemen.
Voor fouten gegenereerd door de ZIM is de waarde "http://www.aortarelease.nl/actor/lsp" verplicht (NB: deze waarde komt niet overeen met die van de SOAP actor, zie par 4.3.1). Voor fouten gegenereerd door de GBx wordt aangeraden de waarde "http://www.aortarelease.nl/actor/gbx" te gebruiken. Andere waarden voor faultactor zijn niet toegestaan.
detail
Het element detail is bedoeld voor applicatie specifieke foutinformatie die gerelateerd is aan het Body element van het SOAP request. Het is verplicht wanneer de inhoud van het Body element niet succesvol verwerkt kon worden. Het mag niet gebruikt worden voor foutinformatie over de header. Wanneer het element detail aanwezig is, betekent dit dat de fout gerelateerd is aan de verwerking van het element Body. Wanneer het element detail niet aanwezig is, dan is de fout niet gerelateerd aan de verwerking van het element Body.
...
Ter illustratie hieronder een voorbeeld van een correcte en een incorrecte SOAP Fault in AORTA.
CORRECT: | Code Block |
|---|
<soapenv:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > |
<faultcode>soapenv:Client</faultcode> |
<faultstring>Het input document is niet valide.</faultstring> |
<faultactor>http <faultactor>http://www.aortarelease.nl/actor/lsp</ |
<lsp:code xmlns:lsp= 'http://www.aortarelease.nl/actor/lsp/soapFault/detail'> |
<lsp:text xmlns:lsp= 'http://www.aortarelease.nl/actor/lsp/soapFault/detail'> |
Een verplicht element mist in het input document: ….. |
|
INCORRECT:
| Code Block |
|---|
<soapenv:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > |
<!-- Onderstaande is fout omdat "dot" notatie niet is toegestaan --> |
<faultcode>soapenv:Client.ZIM.XSD_VALIDATION_ERR</faultcode> |
<!-- Onderstaande is fout omdat child elementen van soapenv:Fault |
niet namespace gekwalificeerd mogen zijn --> |
<soapenv:faultstring> Het input document is niet valide</soapenv:faultstring> |
faultactor>httpfaultactor>http://www.aortarelease.nl/actor/lsp</soapenv: |
<code>MissingMandatoryElement</code> |
<text>Een verplicht element mist in het input document: …..</text> |
<lsp:extraInfo xmlns:lsp= 'http://www.zim.nl/soapFault/detail'> |
Het missende element is verplicht geworden in release…. |
|
| Bij ontvangst van een bericht dat geen well-formed XML bevat, wordt bij voorkeur een HTTP response met status 400 'Bad Request' gegeven. Een applicatie dient ook rekening te houden met een SOAP Client Fault of een HL7v3 Accept Acknowledgement Error. |
...
