HL7 Profile for XML Web Services - OpenHRE.org

flashypumpkincenterSoftware and s/w Development

Dec 14, 2013 (3 years and 9 months ago)

148 views

Web Services Profile for HL7

Draft

Date: August, 28
th

2003

This version:

[insert link to this version here]

Latest version:

[insert link to previous version here]

Editors:

Roberto Ruggeri
, Microsoft


Copy
right © 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 defi
ned in HL7’s Policy and Procedure
Manual dated June 2, 2003) to implement such final HL7 Standard, Microsoft is prepared to grant a non
-
sublicenseable 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 S
UCH
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 spec
ifications 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

Roberto Ruggeri (
rruggeri@microsoft.com
)

David Boliek (
davidbo@microsoft.com
)

12/10/2002

v0.2

General revision

Roberto Ruggeri

7/1/2003


Table of Contents


1

Purpose

................................
................................
................................
........................

3

1.1

Prerequisites

................................
................................
................................
........

3

2

Introduction

................................
................................
................................
.................

3

2.1

An Introduction to the Rele
vant 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

3

The Web Services Profile

................................
................................
...........................

7

3.1

Vision

................................
................................
................................
..................

7

3.2

Requirements

................................
................................
................................
......

8

3.2.1

Use Case Scenario
................................
................................
.......................

8

3.2.2

Det
ailed 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

4

References

................................
................................
................................
.................

16

5

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 i
ndustry 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 docume
nt 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 expos
e 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 Desc
ription 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, de
scription
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), exten
ding 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 de
fined 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. Imple
menter 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 st
andards 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 (B2
B) 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


Figure
1

-

Web Services Architecture



Figure
1

shows the arch
itecture 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 independ
ent 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 metad
ata 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 specific
ations 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.


Futur
e 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 varie
ty 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 c
hanges 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 m
essage 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 He
althcare environment where “plug
-
n
-
play” 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 mo
dules 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 d
o 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 advant
age 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) mess
ages 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 u
ser 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 configu
rations 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 bind
ings 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 defin
e 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



Incl
ude 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 succes
sful 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 p
iece 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 WS
-
I, whose charte
r 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 standa
rd 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 t
he 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 sp
ecifications,
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 Paylo
ad


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 Scen
ario Sequence Diagram



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 workflo
w 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 app
lication 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:



Applicatio
n 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 addr
ess:



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 (sect
ion
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 acc
ording 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
level
s, 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 d
ocument.




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 attachment
s.




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



Me
ssage 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 poin
t.

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

Integ
rity


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, messa
ge 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 re
lated 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
infrastruct
ure 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 payloa
d. 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
policie
s that describe application and business level requirements as well as security
requirements.


Figure
3

-

HL7 Web Service Application Layers


3.3.2

WSDL

A WSDL document can be logically divided into two secti
ons:




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 d
efinitions: 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 use
d 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


<
definitions

xmlns
="
ht
tp://schemas.xmlsoap.org/wsdl/
"

1

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

2

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

3

xmlns:xs
="
http://www.w3.org/2001/XMLSchema
"

4

xmlns:soapenc
="
http://schemas.xmlsoap.org/soap/encoding/
"

5

xmlns:mime
="
http://s
chemas.xmlsoap.org/wsdl/mime/
"

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

6

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

targetNamespace
="
urn:hl7
-
org:v3:ws
">

7


<
types
>

8



<
xs:schema

elementFormDefault
="
qualified
"

targetNamespace
="
urn:hl7
-
org:v3
">

9




<!
--

Include the schema for the messages i
tself
--
>

10




<
xs:include

schemaLocation
="
POLB_MT002102.xsd
"/>

11




<!
--

Include the schema for the messages wrapper
--
>

12




<
xs:include

schemaLocation
="
MCCI_MT000101.xsd
"/>

13




<!
--

Include the schema for the acknowledge message
--
>

14




<
xs:include

schemaLocati
on
="
MCCI_MT000201.xsd
"/>

15




<!
--

Define the body of the message
--
>

16




<
xs:complexType

name
="
MCCI_MT000101.ControlActEvent
">

17





<
xs:sequence
>

18






<
xs:element

name
="
observationOrder
"

type
="
hl7:POLB_MT002102
"/>

19





</
xs:sequence
>

20




</
xs:complexType
>

21




<!
--

Define the element for the message
--
>

22




<
xs:element

name
="
elPOLB_MT002102
"

type
="
hl7:MCCI_MT000101.Message
"/>

23




<!
--

Define the element for the acknowledge
--
>

24




<
xs:element

name
="
elMCCI_MT000201
"

type
="
hl7:MCCI_MT000201.Message
"/>

25



</
xs:schema
>

26


<
/
types
>

27


<
message

name
="
msgPOLB_MT002102In
">

28



<
part

name
="
ptPOLB_MT002102
"

element
="
hl7:elPOLB_MT002102
"/>

29


</
message
>

30


<
message

name
="
msgPOLB_MT002102Out
">

31



<
part

name
="
ptMCCI_MT000201
"

element
="
hl7:elMCCI_MT000201
"/>

32


</
message
>

33


<
portType

name
="
portPO
LB_MT002102
">

34



<
operation

name
="
opPOLB_MT002102
">

35




<
input

message
="
ns:msgPOLB_MT002102In
"/>

36




<
output

message
="
ns:msgPOLB_MT002102Out
"/>

37



</
operation
>

38


</
portType
>

39


<
binding

name
="
bindingPOLB_MT002102
"

type
="
ns:portPOLB_MT002102
">

40



<
soap:binding

styl
e
="
document
"

transport
="
http://schemas.xmlsoap.org/soap/http
"/>

41



<
operation

name
="
opPOLB_MT002102
">

42




<
soap:operation

soapAction
="
urn:#opPOLB_MT002102
"

style
="
document
"/>

43




<
input
>

44





<
soap:body

use
="
literal
"/>

45




</
input
>

46




<
output
>

47





<
soap:body

us
e
="
literal
"/>

48




</
output
>

49



</
operation
>

50


</
binding
>

51


<
service

name
="
svcPOLB_MT002102
">

52



<
port

name
="
POLB_MT002102
"

binding
="
ns:bindingPOLB_MT002102
">

53




<
soap:address

location
="
No Target Address
"/>

54



</
port
>

55


</
service
>

56

</
definitions
>

57


Let’s go over so
me 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 declar
ation 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 sche
mas 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 fo
r 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 2
5: 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 conventi
on 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 secti
on 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 def
ine 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
HTT
P. 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 message
-
oriented 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 mess
age
-
oriented 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 actu
al 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 th
e 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
abs
tract 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 HT
TP. 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 p
roposed 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 d
efine 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 t
he 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]

W3C Extensible Markup Language (XML) 1.0 (Second Edition)
http://www.w3.org/TR/REC
-
xml

[2]

W3C XML Schema
http://www.w3.org/XML/Schema

[3]

W3C Simple Object Access Protocol (SOAP) 1.1
http://www.w3.org/TR/SOAP/

[4]

W3C Web Services Description Language (WSDL) 1.1
http://www.w3.org/TR/wsdl

[5]

IETF WS
-
Attachments specification
http://www.ietf.org/i
nternet
-
drafts/draft
-
nielsen
-
dime
-
soap
-
01.txt

[6]

IETF DIME specification
http://www.ietf.org/internet
-
drafts/draft
-
nielsen
-
dime
-
02.txt

[7]

OASIS WS
-
Security specification
http://www.oasis
-
open.org/committees/wss/

[8]

WS
-
Routing specification
http://msdn.microsoft.com/libr
ary/default.asp?url=/library/en
-
us/dnglobspec/html/ws
-
routing.asp

(submitted as a note to W3C)

[9]

XML Web Services Specifications
http://msdn.microsoft.com/webservices/und
erstanding/specs/default.aspx

[10]

HL7 Version 3 Ballot
http://www.hl7.org/v3ballot/html/foundationdocuments/welcome/index.htm

[11]

WS
-
I Basic Profile Version 1.0
http://www.ws
-
i.org/Profiles/Basic/2002
-
10/BasicProfile
-
1.0
-
WGD.htm

[12]

WS
-
I Testing Tools
http://www.ws
-
i.org/implementation.aspx

[13]

O
ASIS 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 sec
tion:
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 M
essage 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"


<?
x
ml

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_I
N002120'/>



<
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.98
76.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'

exte
nsion
='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 20
0 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.o
rg/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'

e
xtension
='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:se
rvedBy
>



</
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:ver
sionId
>
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

cod
e
='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.


<
definitions

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

1

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

2

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

3

xmlns:xs
="
http://www.w3.org/2001/XMLSchema
"

4

xmlns:soapenc
="
http://schemas.xmlsoap.org/soap/encoding/
"

5

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

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

6

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

targetNamespace
="
urn:hl7
-
org:v3:ws
">

7


<
types
>

8



<
xs:schema

elementFormDefault
="
qualified
"

targetNamespace
="
urn:hl7
-
org:v3
">

9




<
xs:element

name
="
hl7Message
">

10





<
xs:complexType
>

11






<
xs:sequence
>

12







<
xs:any
/>

13






</
xs:sequence
>

14





</
xs:co
mplexType
>

15




</
xs:element
>

16



</
xs:schema
>

17


</
types
>

18


<
message

name
="
msgHl7MessageIn
">

19



<
part

name
="
ptHl7Message
"

element
="
hl7:hl7Message
"/>

20


</
message
>

21


<
message

name
="
msgHl7MessageOut
">

22



<
part

name
="
ptHl7Message
"

element
="
hl7:hl7Message
"/>

23


</
message
>

24


<
portType

name
="
portHl7Message
">

25



<
operation

name
="
opHl7Message
">

26




<
input

message
="
ns:msgHl7MessageIn
"/>

27




<
output

message
="
ns:msgHl7MessageOut
"/>

28



</
operation
>

29


</
portType
>

30


<
binding

name
="
bindingHl7Message
"

type
="
ns:portHl7Message
">

31



<
soap:binding

style
="
document
"

transport
="
http://schemas.xmlsoap.org/soap/http
"/>

32



<
operation

name
="
opHl7Message
">

33




<
soap:operation

soapAction
="
urn:#opHl7Message
"

style
="
document
"/>

34




<
input
>

35





<
soap:body

use
="
literal
"/>

36




</
input
>

37




<
output
>

38





<
soap:body

use
="
literal
"/>

39




</
output
>
"

40



</
operation
>

41


</
binding
>

42


<
service

name
="
svcHl7Message
">

43



<
port

name
="
Hl7Message
"

binding
="
ns:bindingHl7Message
">

44




<
soap:address

location
="
No Target Address
"/>

45



</
port
>

46


</
service
>

47

</
definitions
>

48

As you can see, the WSDL d
efinition 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 opt
ion 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 addresse
d 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 attachmen
ts (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
in
cluded in future versions of this document.