Content Comparison

Een WSDL in AORTA dient als documentatie en contract, omdat de WSDL precies beschrijft aan wat voor service de gegevensleverancier zich gecommitteerd heeft.

Inhoud WSDL

Deze paragraaf beschrijft de inhoud van een AORTA WSDL stap voor stap.

...

In de WSDL worden allereerst benodigde XML Schema's gedeclareerd als WSDL Types. Hieronder volgt een uitleg aan de hand van een voorbeeld.

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

<definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"

             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

             xmlns="http://schemas.xmlsoap.org/wsdl/"

             xmlns:hl7="urn:hl7-org:v3"

             targetNamespace="urn:hl7-org:v3"

             name="VerstrekkingsLijstquery">

   <documentation> WSDL implementatie van VerstrekkingsLijstquery

   </documentation>

   <types>

      <xsd:schema targetNamespace="urn:hl7-org:v3" elementFormDefault="qualified">

         <xsd:include schemaLocation="../schemas_codeGen/QURX_IN990111NL.xsd"/>

      </xsd:schema>

      <xsd:schema targetNamespace="urn:hl7-org:v3" elementFormDefault="qualified">

         <xsd:include schemaLocation="../schemas_codeGen/QURX_IN990113NL.xsd"/>

      </xsd:schema>

   </types>

Eerst is er een inleidend deel, daarna worden schema’s gekoppeld. De schema's worden opgenomen met een schema-include om een en ander beknopt, leesbaar en onderhoudbaar te houden. Er zijn in dit geval twee schema's:

...

Vervolgens worden de nodige berichten gedeclareerd als WSDL Message. De berichten krijgen een unieke naam: die van de interactie.

<message name="QURX_IN990111NL">

      <part name="body" element="hl7:QURX_IN990111NL"/>

   </message>

   <message name="QURX_IN990113NL">

      <part name="body" element="hl7:QURX_IN990113NL"/>

   </message>

Er zijn ook twee verschillende berichten:

...

De verschillende samenhangende interacties uit het Storyboard worden vertaald naar WSDL Port Types. Hierin zijn bij elkaar horende in- en outputs gekoppeld tot WSDL operations.

 <portType name="VerstrekkingsLijstquery_PortType">

      <operation name="VerstrekkingsLijstquery_QueryResponse">

         <input message="hl7:QURX_IN990111NL"/>

         <output message="hl7:QURX_IN990113NL"/>

      </operation>

   </portType>

Hierboven is een operation getoond volgens het synchrone model van berichtenuitwisseling: het antwoord op de query komt synchroon binnen over hetzelfde SOAP en HTTP request/response paar. Dit levert de volgende operation op: VerstrekkingsLijstquery_QueryResponse. Deze bestaat weer uit de eerder gedefinieerde berichten, die als input en output message zijn gedefinieerd.

...

In sommige gevallen is bij een HL7v3-interactie die verzonden wordt meer dan één interactie als antwoord mogelijk. WSDL staat dit niet toe: iedere WSDL-operation mag maximaal één input en één output hebben. De oplossing is een samengesteld xsd element te maken waarin alle HL7v3-antwoordinteracties mogelijk zijn. In onderstaand fragment is deze stijl te zien. Er wordt aan het schema één extra element toegevoegd, met een keuze tussen beide HL7v3-interacties. Dit element heet [request-interaction-id]Response. Dit element wordt vervolgens gebruikt in de message definitie en de operation, zodat de operation weer een enkele output heeft.

<types>
  <xsd:schema targetNamespace="urn:hl7-org:v3" elementFormDefault="qualified"

              xmlns:hl7="urn:hl7-org:v3" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    ...

    <xsd:include schemaLocation="../schemas/COMT_IN800310.xsd" />

  </xsd:schema>

  <xsd:schema targetNamespace="urn:hl7-org:v3" elementFormDefault="qualified"

              xmlns:hl7="urn:hl7-org:v3" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:include schemaLocation="../schemas/COMT_IN800320.xsd" />

  </xsd:schema>

  <xsd:schema targetNamespace="urn:hl7-org:v3" elementFormDefault="qualified"

              xmlns:hl7="urn:hl7-org:v3" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="COMT_IN800300Response">
      <xsd:complexType>
        <xsd:choice>
          <xsd:element ref="hl7:COMT_IN800310"/>
          <xsd:element ref="hl7:COMT_IN800320"/>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
</types>
...

<message name="COMT_IN800300Response">
  <part name="body" element="hl7:COMT_IN800300Response" />
</message>
<portType name="OverdrachtVerantwoordelijkheid_PortType">
   ...

  <operation name="OverdrachtVerantwoordelijkheid_VerzoekOverdrachtVervallen">
    <input message="hl7:COMT_IN800300" />
    <output message="hl7:COMT_IN800300Response" />
  </operation>
</portType>

De WSDL Port Types worden gekoppeld aan WSDL Bindings waar meer details over de SOAP-interactie gegeven worden. Hier wordt gespecificeerd dat de stijl van gegevensuitwisseling ”document/literal” is.

In de Binding wordt ook de waarde van SOAPAction bepaald. Deze SOAPAction komt terug in de HTTP Header, zie paragraaf 4.4.

  <binding type="hl7:VerstrekkingsLijstquery_PortType"

            name="VerstrekkingsLijstquery_Binding">

      <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

      <operation name="VerstrekkingsLijstquery_QueryResponse">

         <soap:operation soapAction="urn:hl7-org:v3/VerstrekkingsLijstquery_QueryResponse"/>

         <input>

            <soap:body use="literal"/>

         </input>

         <output>

            <soap:body use="literal"/>

         </output>

      </operation>

   </binding>

Ten slotte wordt van de WSDL Bindings een WSDL Service gemaakt, die het webadres van een specifieke webservice geeft.

   <service name="VerstrekkingsLijstquery_Service">

      <port binding="hl7:VerstrekkingsLijstquery_Binding"

            name="VerstrekkingsLijstquery_Port">

         <!--Deze service location URI verwijst niet naar een echt bestaande webservice. -->

         <soap:address location="http://www.xis.nl/VerstrekkingsLijstquery"/>

      </port>

   </service>

</definitions>

De waarde van "location" is hier nog fictief. Zie paragraaf 5.2 voor meer details.

Anchor
Locatie van een webservice Locatie van een webservice

Locatie van een webservice

De ZIM of een GBx vervullen in HL7v3-terminologie zogenaamde Application Roles. Een WSDL beschrijft de webservice voor iedere Application Role. Nictiz levert WSDL’s waarin alleen de locatie (de url) van de service nog niet definitief is. Ieder GBx die een webservice aanbiedt in AORTA, biedt ook de echte locatie van de webservice.

...

Voor het opvragen van medicatie is er bijvoorbeeld een "VerstrekkingsLijstquery.wsdl" bestand waarin de locatie van de webservice nog niet definitief is ingevuld. Als locatie staat er:

<soap:address location="http://www.gbx.nl/VerstrekkingsLijstquery" />

Voor ieder GBx komt er dan een specifieke invulling van de locatie. Stel dat er een GBx is met het (fictieve) adres http://www.gbx1.nl, dan kan de ZIM deze webservice aanroepen met onderstaande webservice locatie.

<soap:address location="http://www.gbx1.nl/VerstrekkingsLijstquery" />

De padnamen zijn verplicht: http://www.gbx1.nl/VerstrekkingsLijstquery is goed, http://www.gbx1.nl/VerstrekkingsLijstquery.py of

...

Een GBx-applicatie mag maar één hostname gebruiken voor alle webservices die de GBx-applicatie aanbiedt. Dus in bovenstaand voorbeeld wordt de webservice locatie van een Voorschriftquery van dezelfde GBx-applicatie:

<soap:address location="http://www.gbx1.nl/Voorschriftquery" />

Dit om te voorkomen dat de ZIM een registratie moet bijhouden van alle webservices per GBx, met de bijbehorende plicht voor GBx'en om deze aan te melden en wijzigingen door te geven.[1]

...

• VerstrekkingsLijstQueryBatch_Port (aangeroepen door initiërend GBx bij ZIM),
• VerstrekkingsLijstQuery_Port (aangeroepen door ZIM bij reagerend GBZ).

Paragraaf 5.5 bevat illustraties van de html-documentatie van deze webservice in Figuur 8 en Figuur 9.

...

De eerste twee genoemde wijziging zijn het belangrijkst: een nieuwe servicenaam en een nieuwe (verplichte) padnaam voor de webservice locatie. Deze padnaam bevat het versienummer direct na de hostnaam van het GBx en/of ZIM.

Anchor
WSDL documentatie WSDL documentatie

WSDL documentatie

Bij ieder WSDL bestand wordt ook documentatie in HTML formaat geleverd. Deze bevat een grafische weergave van de communicatie op HTTP-niveau en een overzicht van de relevante parameters uit de WSDL. Figuur 8 en Figuur 9 bevatten een illustratie van deze HTML-documentatie voor VerstrekkingsLijstQuery.wsdl.

...