Web Services Profile for HL7
Draft
Date: August, 28th 2003
This version:
[insert link to this version here]
Latest version:
[insert link to previous version here]
Editors:
Roberto Ruggeri, Microsoft
Copyright © 2003 [insert copyright notice here]. All Rights Reserved.
Notice
If part(s) of this contribution is(are) included in a final HL7 Standard, and if Microsoft has patent rights
(pending and/or issued patents) that are Essential Patent Claims (as defined in HL7’s Policy and Procedure
Manual dated June 2, 2003) to implement such final HL7 Standard, Microsoft is prepared to grant a nonsublicenseable license to the Essential Patent Claims of those Microsoft patent rights that read on this
contribution on reasonable and non-discriminatory terms and conditions, provided a reciprocal license is
granted to Microsoft.
MICROSOFT’S CONTRIBUTION AND THE INFORMATION CONTAINED HEREIN IS PROVIDED
"AS IS" AND WITH ALL FAULTS, AND MICROSOFT HEREBY DISCLAIMS ALL OTHER
WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY. IN NO EVENT WILL
MICROSOFT BE LIABLE TO ANY OTHER PARTY, INCLUDING HL7 OR ITS MEMBERS, FOR
THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE,
LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL
DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN
ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT,
WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH
DAMAGES.
Abstract
Status of this document
The document is currently in draft format and subject to review by the relevant HL7 SIGs
and TCs before inclusion in the HL7 v3 ballot. This document will be updated to reflect
changes in the referenced specifications and publications as well as to include new
standards as they are published and they become part of the XML Web Services family
of standards.
Revision History
v0.1
Document creation
v0.2
General revision
Roberto Ruggeri (rruggeri@microsoft.com)
David Boliek (davidbo@microsoft.com)
Roberto Ruggeri
12/10/2002
7/1/2003
Table of Contents
1
2
3
4
5
Purpose........................................................................................................................ 3
1.1
Prerequisites ........................................................................................................ 3
Introduction ................................................................................................................. 3
2.1
An Introduction to the Relevant Standards ......................................................... 6
2.1.1
SOAP 1.1 .................................................................................................... 6
2.1.2
WSDL 1.1 ................................................................................................... 6
2.1.3
UDDI........................................................................................................... 6
2.1.4
Why are XML Web Services Relevant to HL7? ........................................ 6
The Web Services Profile ........................................................................................... 7
3.1
Vision .................................................................................................................. 7
3.2
Requirements ...................................................................................................... 8
3.2.1
Use Case Scenario....................................................................................... 8
3.2.2
Detailed Workflow...................................................................................... 9
3.2.2.1 WSDL Processing ................................................................................... 9
3.2.2.2 SOAP Message Construction................................................................ 10
3.2.2.3 Sending the SOAP Message ................................................................. 10
3.2.2.4 SOAP Message Receipt Processing ...................................................... 10
3.2.2.5 SOAP Reply Message Construction ..................................................... 10
3.2.2.6 Sending the SOAP Reply Message ....................................................... 11
3.2.2.7 SOAP Reply Message Processing ........................................................ 11
3.3
Design ............................................................................................................... 12
3.3.1
Application Layers .................................................................................... 12
3.3.2
WSDL ....................................................................................................... 12
3.3.3
Bindings/Transports .................................................................................. 16
3.3.4
SOAP Header Extensions ......................................................................... 16
References ................................................................................................................. 16
Appendix ................................................................................................................... 17
5.1
Convention Used in WDSL Document............................................................. 17
5.2
Sample SOAP Request and Response .............................................................. 17
5.2.1
SOAP Request .......................................................................................... 17
5.2.2
SOAP Response ........................................................................................ 19
5.3
Sample Not Typed WSDL Document .............................................................. 19
5.4
Attachments ...................................................................................................... 21
5.5
Applicability to Other HL7 Standards .............................................................. 21
1 Purpose
The purpose of the Web Services Profile (WSP) is to provide implementation guidelines
to promote interoperability between implementers that want to exchange HL7 Version 3
messages using standards that fall under the general definition of Web Services. With the
objective of leveraging the effort of the industry to promote interoperability,
recommendations from organizations like WS-I, W3C and other will be taken into
account. A complete list of standards, publications and organizations involved in the
development of the standards referenced in this document is available in the References
section.
In the appendix 5.5 we will explore the applicability of this profile to other HL7
standards like CDA and HL7 Messaging 2.x and 2.XML.
1.1 Prerequisites
This document is meant to illustrate an application of several standards to the context of
HL7 and therefore does not provide a full explanation of the specifications referenced. To
fully comprehend this document it is suggested that the reader meets the following
prerequisites:
 A knowledge of XML and XML Schema Language as defined in [1] and [2]
 A knowledge of the SOAP protocol as defined in [3]
 A knowledge of the WSDL format as defined in [4]
 A knowledge of the HL7 Version 3 ballot as defined in [10]
A complete list of resources can be found in the References chapter.
2 Introduction
Web Services are a way for applications to expose software services using standard
interoperable protocols, regardless of the platform on which they are implemented.
The development of interoperable standards and the focus on communication and
collaboration among people and applications have created an environment where Web
Services are becoming the protocol/technology of choice for application integration.
There are many definitions of Web Service, but almost all definitions have these things in
common:
 Web Services expose useful functionality to users through the Web Services
protocols.
 Web services provide a way to describe their interfaces in enough detail to allow a
user to build a client application to talk to them. This description is usually
provided in an XML document called a Web Services Description Language
(WSDL) document.
 Web services are registered so that potential users can find them easily. This is
done with Universal Discovery Description and Integration (UDDI).
Advanced Web Services Protocols (WS-* Protocols) are built on top of the foundation
for Web Services constituted by XML, SOAP and WSDL to express additional
functionalities. These are specifications that are developed with the intention of broad
adoption and interoperability and focus on security, reliability, transactions, description
and discovery.
While the first implementations of Web Services were build with the Internet in mind,
there is really nothing in the specifications themselves that prevents the use of these
standards with other protocols (protocol binding), extending the use of Web Services
from business to business (B2B) integration over the internet and HTTP, to Enterprise
Application Integration (EAI) inside the company’s firewall using different protocols like
TCP/IP or MLLP (Minimum Lower Layer Protocol as defined by HL7).
Here are some of the design principles of the Web Services standards:
 Modularity: the standards were built with extensibility in mind so that a gradual
approach could be taken to the development of a complete messaging
infrastructure. Implementer can pick and choose what standards to implement
based on their needs. All of the specifications included in the Web Services
standards are very simple and easy to use and can be composed for additional
functionality.
 General purpose: Web Services standards are not tied to any particular
messaging protocol or platform forming the basis for a universal mean of
communication between organizations, applications and processes. Being built on
SOAP and XML imposes very few requirements on applications that can be
deployed on traditional servers and desktops, down to PDA and embedded
systems like medical devices. The nature of these standards allows also for
multiple integration paradigms like Enterprise Application Integration (EAI),
Business to Business (B2B) and Peer to Peer (P2P). In addition Web Services
specifications support both synchronous and asynchronous communications.
 Based on interoperable standards: one important factor that determines the
rapid development and adoption of Web Services standards is the fact that these
are build on other standards like XML, HTTP and SOAP were multiple
implementations on multiple platform are available
WS-Security,
Secure Conversation, Trust, …
Reliable
Messaging
Transactions
WS-Transactions,
WS-Coordination
…
WSDL, Policy
Security
Metadata
Figure 1 - Web Services Architecture
Messaging WS-Addressing …
XML and SOAP XSD, XPath, …
Network Transports HTTP, TCP, UDP, …
Figure 1 shows the architecture and the relation between the different WS-* protocols. At
the bottom of the stack, different network transports provide connectivity between
applications and service consumers and providers. The rest of the WS-* specifications are
largely independent from the specific network transport chosen.
XML and SOAP, along with the XML standards like XML Schema Definition, XPath
and so on, constitute the basis on which the rest of the specifications are built upon. Core
messaging standards like WS-Addressing provide the infrastructure for message
exchange allowing transport independent addressing and enabling composition with other
specifications like WS-Security.
The information that is needed beyond what WSDL provides (ports, types …), is
specified by metadata and policies attached to the message definition. Policies define a
base set of constructs that can be used and extended by other Web Services specifications
to describe a broad range of service requirements, preferences and capabilities.
Other specifications address security (in order to be able to ensure the confidentiality,
integrity, and privacy of a SOAP message and still being able to route messages through
various intermediaries), reliable messaging and transactions among different parties.
Future versions of this document will include recommendations for additional WS-*
protocols to take advantage of these additional functionalities as detailed in the roadmap
in §3.1.
2.1 An Introduction to the Relevant Standards
2.1.1 SOAP 1.1
From [3]:
SOAP is a lightweight protocol for the exchange of information in a
decentralized, distributed environment. It is an XML-based protocol that consists
of three parts: an envelope that defines a framework for describing what is in a
message and how to process it, a set of encoding rules for expressing instances of
application-defined data types, and a convention for representing remote
procedure calls and responses. SOAP can potentially be used in combination with
a variety of other protocols.
This profile does not specifically address SOAP 1.2 in this particular version. SOAP 1.2
has recently become a W3C recommendation, but implementations are not yet widely
available. Future versions of this document will address the changes required by SOAP
1.2. Note that compliancy with the WS-I Basic Profile allows for a smoother migration to
SOAP 1.2 as most of the features from SOAP 1.1 that did not make it to version 1.2 are
deprecated in the profile.
2.1.2 WSDL 1.1
From [4]:
WSDL defines an XML-based grammar for describing network services as a set
of endpoints that accept messages containing either document-oriented or
procedure-oriented information. The operations and messages are described
abstractly. They are bound to a concrete network protocol and message format to
define an endpoint. Related concrete endpoints are combined into abstract
endpoints (services). WSDL is extensible to allow the description of endpoints
and their messages regardless of what message formats or network protocols are
being used to communicate.
2.1.3 UDDI
From [13]:
The Universal Description, Discovery, and Integration (UDDI) specification
defines a SOAP-based Web service for locating WSDL-formatted protocol
descriptions of Web services. UDDI provides a foundation for developers and
administrators to readily share information about internal Web services across the
enterprise and public Web services across the Internet.
2.1.4 Why are XML Web Services Relevant to HL7?
In order to foster adoption of the HL7 standard is important to reuse wherever possible
standards and efforts carried on by broad industry initiatives such as this one.
3 The Web Services Profile
3.1 Vision
The ideal situation that we will be looking at is a Healthcare environment where “plug-nplay” interoperability via Web Services is a reality. In this environment Independent
Software Vendors (ISV) and corporate developers implementing HL7 interfaces can
write generic and reusable classes, subroutines, and modules consistent with the
guidelines set forth by the HL7 standard for Web Services standards in order to handle
HL7 message traffic from a potentially unlimited number of connecting applications and
services. Applications that “expose” HL7 messages will do so according to the HL7 Web
Services Profile (WSP) guidelines; “consumers” of HL7 messages can be written without
prior knowledge of the application that they will ultimately end up talking to. In addition,
this “plug-n-play” environment will take advantage of supporting discovery protocols
such as UDDI to break the rigidity of the current hard-coded message routing
infrastructures of most Healthcare enterprises.
As an example, imagine an application that consumes ADT (Admission Discharge
Transfer) messages that is installed in a hospital data center, using the Web Services
discovery protocols such as UDDI is possible to get the physical endpoints of all the
applications that expose the ADT service. The list of service providers can be presented
to the user or administrator that is installing the application and the specific endpoint set
as part of the configuration steps. Protocols, document definitions, security and policies
are defined in the service descriptions and all the complex interfacing configurations are
avoided.
Attached to the definition of the Web Service will be a set of policies that specify
additional messaging requirements like security, message reliability levels, transactions
and so on.
Once the service is located, the appropriate bindings and configurations are accomplished
and the applications are ready to start exchanging messages in a secure, reliable way, all
of this with minimal user intervention.
In order to make this vision a reality we are presenting the work in this document to
coordinate the work done in the industry around Web Services and the development of
the HL7 standards.
For the development of the HL7 WSP we chose a phased approach, where we gradually
introduce Web Services specifications as these standards mature and consolidate and
solid implementations become available on the market.
This is the roadmap set for the development of this profile at the time of writing:



Include SOAP 1.1 [3], WSDL 1.1 [4] to define the HL7 WSP and consider
recommendations set in the draft WS-I Basic Profile [11].
Include WS-Security and WS-Policy specifications and recommendations from
the final WS-I Basic Profile and the draft WS-I Security Profile
Include changes for SOAP 1.2

Future versions of the WSP will include additional specifications and refinements
as well as changes to the vision/scope scenario as the Web Services specifications
mature
3.2 Requirements
In order for this recommendation to be successful and ultimately enable the realization of
the previously stated vision there are organizational, process, and technical requirements
that must be met.
Web Services are supported by the work of several organizations each contributing their
respective piece of the complete solution. Among these are:




W3C
IETF
OASIS
WS-I
From an HL7 organizational perspective it is recommended that the ongoing efforts of
coordination with other SDOs be continued and extended to other organizations like WSI, whose charter is to promote interoperability among different Web Services standards
implementations by writing profiles such as this one.
From a process perspective the introduction of the HL7 WSP establishes the beginning of
a continual process that will facilitate the adoption and implementation of HL7 solutions
based on Web Services and will contribute to the evolution of the Web Services
standards.
From a technical perspective the HL7 interoperability recommendation must be based on
interoperable industry standard specifications and protocols. The HL7 WSP must also
support the concept of strongly-typed definitions and the ability to enforce message
correctness.
Particular focus should be put on balancing the ease of implementation with the technical
merits of the WSP by providing recommendations that take also into consideration the
landscape of tools and technologies that are available to implementers of the profile.
3.2.1 Use Case Scenario
This use case scenario will serve as an illustration of how the applicable specifications,
WSDL, SOAP, WS-I Basic Profile, and HL7, are applied to accomplish a specific task
and will highlight the various areas that need to be addressed as part of the ongoing
profile development. This scenario corresponds to the “Send Message Payload – with
Accept Acknowledgement (MCCI_ST000001)” storyboard found in the Version 3 Ballot.
The following interaction diagram illustrates the basic flow and the HL7 message types
referenced in the scenario.
Figure 2 - HL7 WS Scenario Sequence Diagram
MCCI_MT000101:Message_Sender:
Requests accept ack
MCCI_MT000201:Message_Reciever
:Returns accept ack
Send Message Payload: MCCI_MT000101()
Accept Acknowlegement: MCCI_MT000201
3.2.2 Detailed Workflow
In accomplishing this simple task the Message Sender and Message Receiver will take
advantage of the guidelines set in this document. Following is a step-by-step breakdown
of the workflow illustrating the application of each of these standards.
The Message Receiver is the application or service that exposes the Web Service and
provides the WSDL document that is analyzed in §3.3.2.
The Message Sender is the application or service that acts as a client and consumes the
Web Service.
Note: the workflow is intended to outline the pertinent tasks and is not prescriptive as to
the sequence of fine grained steps.
3.2.2.1 WSDL Processing
 Once the definition for the message is located and downloaded to the client machine,
the Message Sender can process the WSDL describing the selected business service.
Steps include:
o Retrieve necessary schemas and document definitions referenced in the
message definition (WSDL)
o Parse the schemas/documents
o Cache information necessary to subsequently construct the specified SOAP
message according to WSDL specifications (proxy)
o Industry standards to address:
 Options for encapsulating the HL7 payload (SOAP body, attachments,
MIME, DIME, etc) (section 5.4)
3.2.2.2 SOAP Message Construction
 Message Sender constructs the HL7 Version 3 message payload, control wrapper and
wrapper (MCCI_MT000101).

Message Sender constructs SOAP message headers.
o Industry standards to address:
 Application of WS-I Basic Profile recommendations [11]

Message Sender constructs SOAP message body and or attachments.

Message Sender secures the SOAP message. Steps include:
o Message encryption
o Message signing
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …
3.2.2.3 Sending the SOAP Message
 Message Sender sends the SOAP message to the selected service end point.
o Industry standards to address:
 Transport protocol bindings (section 3.3.3)
 Routing specification

Message is routed and delivered to service end point.
3.2.2.4 SOAP Message Receipt Processing
 Message Receiver receives SOAP message containing the MCCI_MT000101
document.

Message Receiver filters according to WS-Security policy and validates the message
for:
o Authenticity – message signature verification
o Integrity – message encryption verification
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …

Message Receiver extracts, parses, and validates encapsulated MCCI_MT000101
document.
o Industry standards to address:
 Document validation criteria
3.2.2.5 SOAP Reply Message Construction
 Message Receiver constructs the MCCI_MT000201 acknowledgement document.

Message Receiver constructs SOAP reply message headers.
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …

Message Receiver constructs SOAP reply message body and or attachments.

Message Receiver secures the SOAP reply message. Steps include:
o Message encryption
o Message signing
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …
3.2.2.6 Sending the SOAP Reply Message
 Message Receiver sends the SOAP reply message to Message Sender’s end point.
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …

Message is routed and delivered to Message Sender’s end point.
3.2.2.7 SOAP Reply Message Processing
 Message Sender receives SOAP reply message containing the MCCI_MT000201
document.

Message Sender filters reply message according to policy and validates the message
for:
o Authenticity – message signature verification
o Integrity – message encryption verification
o Industry standards to address:
 Security policy violation procedures

Message Sender applies remaining Web Services specifications.
o Industry standards to address:
 Application of security and privacy requirements, message reliability
levels, policies …

Message Sender extracts, parses, and validates encapsulated MCCI_MT000201
acknowledgement document.
o Industry standards to address:
 Document validation criteria
3.3 Design
This section will present a description of how the related WS specifications are applied to
the specific scenario outlined in the Requirements section to produce WSDL and SOAP
instance samples.
3.3.1 Application Layers
Enabling HL7 payloads to be delivered in a plug and play fashion over a Web Services
infrastructure is best achieved by supporting a layered and loosely coupled architecture.
The following diagram illustrates application layers involved in a Web Services
communication between a consumer and a provider of a service that want to exchange an
HL7 payload. Appropriate abstraction is maintained at each level to hide implementation
or configuration details in the lower levels. At the upper level we find the actual HL7
payload, moving towards the bottom of the stack we have WS-* protocols that define
policies that describe application and business level requirements as well as security
requirements.
Figure 3 - HL7 Web Service Application Layers
Consumer
Provider
HL7
HL7
WS-*
(Profile, Security, etc)
WS-*
(Profile, Security, etc)
SOAP
SOAP
Transport Bindings
(HTTP, SMTP, MLLP)
Transport Bindings
(HTTP, SMTP, MLLP)
Network
(TCP/IP, UDP)
Network
(TCP/IP, UDP)
3.3.2 WSDL
A WSDL document can be logically divided into two sections:


Abstract definitions: defines things like datatypes, messages, and the way messages
can be combined as request/response pairs for RPC-like operations and how the
messages will be sent using a particular protocol, such as SOAP or HTTP-GET.
Concrete definitions: defines the physical location of the endpoint.
The following is an example WSDL document describing the service supporting the
previously described usage scenario. The document provided shows a strongly typed
service definition that can be used to enforce XML Schema validation for message
instances, an example of WSDL that does not enforce types is presented in the appendix
5.3.
Figure 4 - Strongly Typed WSDL Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:ns="urn:hl7-org:v3:ws"
xmlns:hl7="urn:hl7-org:v3" targetNamespace="urn:hl7-org:v3:ws">
<types>
<xs:schema elementFormDefault="qualified" targetNamespace="urn:hl7-org:v3">
<!-- Include the schema for the messages itself -->
<xs:include schemaLocation="POLB_MT002102.xsd"/>
<!-- Include the schema for the messages wrapper -->
<xs:include schemaLocation="MCCI_MT000101.xsd"/>
<!-- Include the schema for the acknowledge message -->
<xs:include schemaLocation="MCCI_MT000201.xsd"/>
<!-- Define the body of the message -->
<xs:complexType name="MCCI_MT000101.ControlActEvent">
<xs:sequence>
<xs:element name="observationOrder" type="hl7:POLB_MT002102"/>
</xs:sequence>
</xs:complexType>
<!-- Define the element for the message -->
<xs:element name="elPOLB_MT002102" type="hl7:MCCI_MT000101.Message"/>
<!-- Define the element for the acknowledge -->
<xs:element name="elMCCI_MT000201" type="hl7:MCCI_MT000201.Message"/>
</xs:schema>
</types>
<message name="msgPOLB_MT002102In">
<part name="ptPOLB_MT002102" element="hl7:elPOLB_MT002102"/>
</message>
<message name="msgPOLB_MT002102Out">
<part name="ptMCCI_MT000201" element="hl7:elMCCI_MT000201"/>
</message>
<portType name="portPOLB_MT002102">
<operation name="opPOLB_MT002102">
<input message="ns:msgPOLB_MT002102In"/>
<output message="ns:msgPOLB_MT002102Out"/>
</operation>
</portType>
<binding name="bindingPOLB_MT002102" type="ns:portPOLB_MT002102">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="opPOLB_MT002102">
<soap:operation soapAction="urn:#opPOLB_MT002102" style="document"/>
<input>
<soap:body use="literal"/>
46
47
48
49
50
51
52
53
54
55
56
57
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="svcPOLB_MT002102">
<port name="POLB_MT002102" binding="ns:bindingPOLB_MT002102">
<soap:address location="No Target Address"/>
</port>
</service>
</definitions>
Let’s go over some of the details of the WSDL document:
Lines 1-7: relevant namespaces are defined in this section, note that the namespace for
the document is defined as "urn:hl7-org:v3:ws", this convention is arbitrary and can
be changed.
Lines 8-27: this is the declaration of the types that will be used for the definition of the
messages.
Line 11: the schema that defines the specific HL7 Version 3 message that will be
exchanged is included. In this case the definition for POLB_MT002102 has
been included. Different schemas can be included to define Web Services for
other HL7 Version 3 message types.
Line 13: the schema that defines the message wrapper is included
Line 15: the schema that defines the message acknowledge is included
Lines 17-21: if this section the type for ControlActEvent is redefined to correctly
identify the payload of the HL7 Version 3 message to be of type
POLB_MT002102
Line 23: the element that defines the type of the input parameter is declared. This
element will be used later in the document.
Line 25: the element that defines the type of the output parameter is declared. This
element will be used later in the document.
Lines 28-30: this is where the input parameter is defined; the element previously declared
in the types section is used. The convention used to define input parameters is
“msg<HL7 Message Name>In”, in this case msgPOLB_MT002102In. The
convention is arbitrary and can be changed.
Lines 31-33: this is where the output parameter is defined; the element previously
declared in the types section is used. The convention used to define output
parameters is “msg<HL7 Message Name>Out”, in this case
msgPOLB_MT002102Out. The convention is arbitrary and can be changed.
Lines 34-39: this is where input and output parameters are combined together to define a
port type. The convention used for port types is “port<HL7 Message Name>”, in this
case portPOLB_MT002102. The convention is arbitrary and can be changed.
Lines 40-51: the port type defined above is then bound to a specific protocol, in this case
HTTP. The convention used to define bindings is “binding<HL7 Message Name>”,
in this case bindingPOLB_MT002102. The convention is arbitrary and can be
changed.
Line 41: the particular binding chosen in this case is HTTP. This line also defines the
style used for including the HL7 message payload in the SOAP body. In this
case the style selected is “document”, for message-oriented exchanges this is the
most appropriate setting.
Line 45: this setting defines the encoding for the HL7 message payload that will be
included in the SOAP body for the input parameter. The setting “literal”
specifies that the payload should be included as-is in the body. For messageoriented exchanges this is the most appropriate setting and the recommended
value when selecting “document” for the binding style.
Line 46: this setting defines the encoding for the HL7 message payload that will be
included in the SOAP body for the output parameter. The setting “literal”
specifies that the payload should be included as-is in the body. For messageoriented exchanges this is the most appropriate setting and the recommended
value when selecting “document” for the binding style.
Lines 52-56: in this section the abstract Web Service definition declared so far in the
WSDL document is bound to an actual implementation and a real endpoint. The
convention used to define services is “svc<HL7 Message Name>”, in this case
svcPOLB_MT002102. The convention is arbitrary and can be changed.
The WSDL presented was developed according to the guidelines set in the WS-I Basic
Profile at [11] and tested with the draft version of the WS-I Testing Tools available at
[12].
This example also demonstrates that typical HL7 message patterns can be standardized as
abstract WSDL definitions and then implemented in an enterprise to provide much of the
necessary underpinnings for a plug-n-play environment.
A list of conventions used in the sample WSDL document is provided in the appendix
5.1.
Sample instances of SOAP messages are provided in the appendix 5.2.
3.3.3 Bindings/Transports
The previous section presented a sample WSDL definition for a service that specified that
a SOAP envelope be delivered over the wire via HTTP. It is possible for WSDL to
specify that the SOAP envelope be delivered over other transport mechanisms such as
SMTP or MLLP.
At the moment of the writing the only widely implemented transport type is HTTP, no
other protocol has been standardized or proposed as a standards besides HTTP itself.
Since SOAP and Web Services are in no way tied to HTTP, it should be expected that
new specification for bindings to other protocols will be developed by the industry.
3.3.4 SOAP Header Extensions
When using the WSDL define above, it is not necessary to define HL7 specific SOAP
header extensions to facilitate inspection and/or routing of the SOAP message based on
the content of the payload. The examples presented in the appendix 5.2 are “on the wire”
message instances formatted according to WSDL definition. The “soap:Body” element
can be queried via XPath to look for HL7 payload specific information.
4 References
[1]
[2]
[3]
W3C Extensible Markup Language (XML) 1.0 (Second Edition)
http://www.w3.org/TR/REC-xml
W3C XML Schema http://www.w3.org/XML/Schema
W3C Simple Object Access Protocol (SOAP) 1.1 http://www.w3.org/TR/SOAP/
[4]
[5]
[6]
[7]
[8]
[9]
[10]
[11]
[12]
[13]
W3C Web Services Description Language (WSDL) 1.1
http://www.w3.org/TR/wsdl
IETF WS-Attachments specification http://www.ietf.org/internet-drafts/draftnielsen-dime-soap-01.txt
IETF DIME specification http://www.ietf.org/internet-drafts/draft-nielsen-dime02.txt
OASIS WS-Security specification http://www.oasis-open.org/committees/wss/
WS-Routing specification
http://msdn.microsoft.com/library/default.asp?url=/library/enus/dnglobspec/html/ws-routing.asp (submitted as a note to W3C)
XML Web Services Specifications
http://msdn.microsoft.com/webservices/understanding/specs/default.aspx
HL7 Version 3 Ballot
http://www.hl7.org/v3ballot/html/foundationdocuments/welcome/index.htm
WS-I Basic Profile Version 1.0 http://www.ws-i.org/Profiles/Basic/200210/BasicProfile-1.0-WGD.htm
WS-I Testing Tools http://www.ws-i.org/implementation.aspx
OASIS UDDI Specifications http://uddi.org/specification.html
5 Appendix
5.1 Convention Used in WDSL Document
All of the following conventions are arbitrary and can be changed.









Element names used in the type section: el<HL7 Message Name>
Input message names: msg<HL7 Message Name>In
Output message name: msg<HL7 Message Name>Out
Part names used in message definitions: pt<HL7 Message Name>
Port types: port<HL7 Message Name>
Operations defined in port types: op<HL7 Message Name>
Bindings: binding<HL7 Message Name>
URN for soapAction: same as the operation name defined in the port type
Services: svc<HL7 Message Name>
5.2 Sample SOAP Request and Response
The sample SOAP request and response presented in this section use the HL7 Version 3
Schemas and sample data developed for HIMSS 2003 HL7 Demo.
5.2.1 SOAP Request
POST /targetAddress/svcPOLB_MT002102.asmx HTTP/1.1
Host: hostAddress
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "urn:#opPOLB_MT002102"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=http://www.w3.org/2001/X_LSchema-instance
xmlns:xsd=http://www.w3.org/2001/X_LSchema
xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:hl7="urn:hl7-org:v3">
<soap:Body>
<elPOLB_MT002102 xmlns="urn:hl7-org:v3"
xmlns:xsi="http://www.w3.org/2001/X_LSchema-instance"
xsi:schemaLocation="urn:hl7-org:v3.\schemas\envPOLB_MT002102.xsd">
<hl7:id root='2.16.840.1.113883.9876.349' extension='347782'/>
<hl7:creationTime value='20030103170600'/>
<hl7:sender>
<hl7:servedBy>
<hl7:id root='2.16.840.1.113883.9876.349' extension='EpicCare'/>
<hl7:name>EpicCare Patiçnt Medical Records</hl7:name>
</hl7:servedBy>
</hl7:sender>
<hl7:receiver>
<hl7:servedBy>
<hl7:id root='2.16.840.1.113883.9876.369' extension='InternalLab'/>
<hl7:name>NeoTool Excellent Lab Systems</hl7:name>
</hl7:servedBy>
</hl7:receiver>
<hl7:versionId>v3r1b3</hl7:versionId>
<hl7:interactionI€cf5 root='2.16.840.1.113883.9876.5'
extension='POLB_IN002120'/>
<hl7:processingCo€'e7 code='P'/>
<hl7:processingMo€'e7Code code='T'/>
<hl7:acceptAckCode code='AL'/>
<hl7:applicationAckCode code='AL'/>
<hl7:hasPayload>
<hl7:observationOrder>
<hl7:id root='2.16.840.1.113883.9876.349' extension='34522'/>
<hl7:code code='P3-30100'
codeSystem='2.16.840.1.113883.6.5'
codeSystemNamç='SNOMED'
codeSystemVersion='20020829'
displayName='Complete_u66 ?lood Count'/>
<hl7:effectiveTime value='20030103170100'/>
<hl7:priorityCode code='N' displayName='Normal'/>
<hl7:participant typeCode='VRF'>
<hl7:assignedEntity>
<hl7:id root='2.16.840.1.113883.9876.210.3' extension='5332443'/>
<hl7:assigneePerson>
<hl7:name>
<hl7:given>Keiko</hl7:given>
<hl7:family>Jones</hl7:family>
</hl7:name>
</hl7:assigneePerson>
</hl7:assignedEntity>
</hl7:participant>
<hl7:patientParticipation>
<hl7:patient>
<hl7:id root='2.16.840.1.113883.9876.211' extension='344253425'/>
<hl7:addr>
<hl7:streetAddressLine>2222 Home Strçet</hl7:streetAddressLine>
<hl7:city>Ann Arbor</hl7:city>
<hl7:state>MI</hl7:state>
<hl7:postalCode>99999</hl7:postalCode>
<hl7:country>USA</hl7:country>
</hl7:addr>
<hl7:telecom value='tel:213-555-4344'/>
<hl7:patientPerson>
<hl7:id root='2.16.840.1.113883.4.1' extension='333224444'/>
<hl7:name>
<hl7:given>George</hl7:given>
<hl7:given>Simon</hl7:given>
<hl7:family>Wigny</hl7:family>
</hl7:name>
<hl7:administrativçGenderCode code='M'
codeSystem='2.16.840.1.113883.5.1'/>
<hl7:birthTime value='19740423'/>
</hl7:patientPerson>
</hl7:patient>
</hl7:patientParticipation>
</hl7:observationOrder>
</hl7:hasPayload>
</elPOLB_MT002102>
</soap:Body>
</soap:Envelope>
5.2.2 SOAP Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/X_LSchema-instance"
xmlns:xsd="http://www.w3.org/2001/X_LSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<elMCCI_MT000201 xmlns="urn:hl7-org:v3"
xmlns:xsi="http://www.w3.org/2001/X_LSchema-instance"
xsi:schemaLocation="urn:hl7-org:v3./schemas/MCCI_MT000201.xsd">
<hl7:id root='2.16.840.1.113883.9876.369' extension='231112'/>
<hl7:creationTime value='2002106170601'/>
<hl7:sender>
<hl7:servedBy>
<hl7:id root='2.16.840.1.113883.9876.369' extension='Internal_Lab'/>
<hl7:name>NeoTool Excellent Lab Systems</hl7:name>
</hl7:servedBy>
</hl7:sender>
<hl7:receiver>
<hl7:servedBy>
<hl7:id root='2.16.840.1.113883.9876.349' extension='EpicCare'/>
<hl7:name>EpicCare Patiçnt Medical Record</hl7:name>
</hl7:servedBy>
</hl7:receiver>
<hl7:versionId>v3r1b3</hl7:versionId>
<hl7:interactionI€cf5 root='2.16.840.1.113883.9876.5'
extension='MCCI_IN000200'/>
<hl7:processingCo€'e7 code='P'/>
<hl7:processingMo€'e7Code code='T'/>
<hl7:has typeCode='AR'>
<hl7:errorDetailCode code='42'/>
<hl7:noteText>This is a notç explaining code 42</hl7:noteText>
<hl7:acknowledges>
<hl7:id root='2.16.840.1.113883.9876.349' extension='347782'/>
</hl7:acknowledges>
</hl7:has>
</elMCCI_MT000201>
</soap:Body>
</soap:Envelope>
5.3 Sample Not Typed WSDL Document
This is a sample WSDL definition that does not enforce any specific type for messages
that are exchanged.
1
2
3
4
5
6
7
8
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:ns="urn:hl7-org:v3:ws"
xmlns:hl7="urn:hl7-org:v3" targetNamespace="urn:hl7-org:v3:ws">
<types>
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<xs:schema elementFormDefault="qualified" targetNamespace="urn:hl7-org:v3">
<xs:element name="hl7Message">
<xs:complexType>
<xs:sequence>
<xs:any/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types>
<message name="msgHl7MessageIn">
<part name="ptHl7Message" element="hl7:hl7Message"/>
</message>
<message name="msgHl7MessageOut">
<part name="ptHl7Message" element="hl7:hl7Message"/>
</message>
<portType name="portHl7Message">
<operation name="opHl7Message">
<input message="ns:msgHl7MessageIn"/>
<output message="ns:msgHl7MessageOut"/>
</operation>
</portType>
<binding name="bindingHl7Message" type="ns:portHl7Message">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="opHl7Message">
<soap:operation soapAction="urn:#opHl7Message" style="document"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>"
</operation>
</binding>
<service name="svcHl7Message">
<port name="Hl7Message" binding="ns:bindingHl7Message">
<soap:address location="No Target Address"/>
</port>
</service>
</definitions>
As you can see, the WSDL definition is greatly simplified because there is no type
declaration and the Web Service method is described as a method accepting generic
XML as input and returning generic XML as output (line 13).
This same definition can be used to exchange a different number of HL7 messages (or
any XML message) and although the type of the messages is not enforced, the SOAP
body can still be queried using XPath expressions to determine the type of the payload
and route the message accordingly.
5.4 Attachments
When sending HL7 messages over Web Services there are two main options:


Include the HL7 message in the SOAP body:
Include the HL7 message as an attachment to the SOAP message
The first option is presented in §3.3.2. Advantages of this option include the fact that the
HL7 data elements are readily available and accessible via XPath expressions.
If the HL7 message is attached to the SOAP message, standards like MIME, DIME or
WS-Attachments can be used. This option is not recommended for HL7 Version 3
messages (and any other HL7 message/document that uses XML as its format) as it does
not provide any significant advantage and creates some issues with the routing of
messages where intermediate SOAP nodes need to decode the attachment in order to
decide what to do with the message. A way to address this particular issue would be to
replicate part (or all) of the HL7 message header in the SOAP body or as SOAP header
extension.
In the case where the HL7 payload is included in SOAP messages as an attachment, the
WSDL definition would need to be modified accordingly. The resulting HL7 Web
Services Profile should address the various methods of encapsulating the payload.
The individual specification for handing attachments will eventually be addressed in
future versions of this document.
At the moment of the writing there is significant consolidation happening in the area of
attachments and new standards or revisions of the current one are expected to be
published in the near future.
5.5 Applicability to Other HL7 Standards
The same concepts described in this document can be applied to other HL7 standards as
follows:

HL7 V2.x: since version 2.x of HL7 Messaging is not natively represented as
XML, the Web Services implementation is forced to use attachments (MIME,
DIME or WS-Attachments) or include the HL7 2.x payload as a string in the
SOAP body. Furthermore some routing information needs to be extracted from


the original 2.x message (MSH, PID …) and included as a SOAP header
extension or in the SOAP body if that information is necessary to route the
message. A profile for version 2.x messages can be included in future versions of
this document.
HL7 V2.XML: HL7 messages in version 2.XML can be easily exchanged using
Web Services and the recommendations set in this document. A profile for
version 2.x messages can be included in future versions of this document.
HL7 CDA: CDA documents can be easily exchanged using Web Services and the
recommendations set in this document. A profile for CDA documents can be
included in future versions of this document.