Appendix V: Web Services for IHE Transactions
V.1 Introduction
“Web Services” has become a catch-all phrase describing a wide range of HTTP transactions over a TCP/IP network. A more precise definition of Web Services implies richer infrastructure capabilities with all transactions built using SOAP messages. This appendix provides the guidelines for specifying the use of SOAP-based Web Services as the messaging infrastructure and transport mechanism for IHE transactions.
V.2 Relevant Standards
Virtually all web services specifications are developed under the auspices of the World Wide Web Consortium (W3C) or the Organization for the Advancement of Structured Information Standards (OASIS). The Web Services-Interoperability organization (WS-I) publishes profiles, which incorporate several existing standards, and constrain them for interoperability. For each profile, WS-I also publishes a test assertion document and corresponding interoperability testing tools for Java and C#.
V.2.1 WS-I Profiles
The Web Services for IHE transactions will be based on SOAP 1.2, and as such they take advantage of the guidelines expressed in the WS-I Basic Profile 2.0 (BP 2.0). Some IHE transactions may also take advantage of the WS-I Basic Security Profile 1.1 (BSP 1.1) and WS-I Reliable Secure Profile 1.0 (RSP 1.0) where applicable.
V.2.2 WS-* Specifications
Based on the requirements of the current WS-I profiles, the Web Services for IHE transactions support the following Web Services standards:
- WS-Addressing
- MTOM
- XOP
- WS-Security
The WS-I Reliable Secure Profile combines several of the above WS-* standards, as well as including:
- WS-SecureConversation
- WS-Trust
- WS-Policy
- WS-ReliableMessaging
In the future, the Web Services for IHE transactions will consider support for this new WS-I profile, or particular WS-* standards as needed by specific use cases.
V.2.3 HL7 Web Services Profile
The HL7 Web Services Profile provides a framework for using Web Services as the transport mechanism for HL7 V3 messages. The framework provides a layered approach to specifying Web Services requirements. IHE will use the same approach as a guideline when specifying Web Services transport for IHE transactions and will do its best to maintain this consistency over time.
V.2.4 XML Namespaces
Table V.2.4-1 lists XML namespaces that are used in this appendix. The choice of any namespace prefix is arbitrary and not semantically significant.
Table V.2.4-1: XML Namespaces and Prefixes
| Prefix | Namespace | Specification |
| wsdl (or default) | http://schemas.xmlsoap.org/wsdl/ | |
| wsoap12 or wsoap | http://schemas.xmlsoap.org/wsdl/soap12/ | |
| wsaw | http://www.w3.org/2006/05/addressing/wsdl | |
| wsa | http://www.w3.org/2005/08/addressing | |
| wsam | http://www.w3.org/2007/05/addressing/metadata | |
| soap12 | http://www.w3.org/2003/05/soap-envelope | |
| soap | Either soap11 or soap12 depending on context | |
| Hl7 | urn:hl7-org:v3 | HL7 V3 XML ITS |
| xsd | http://www.w3.org/2001/XMLSchema | |
| xsi | http://www.w3.org/2001/XMLSchema-instance | |
| lcm | urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0 | |
| rim | urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0 | |
| rs | urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0 | |
| query | urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0 | |
| xds | urn:ihe:iti:xds-b:2007 | |
| xop | http://www.w3.org/2004/08/xop/include |
V.3 Web Services Requirements
The requirements in this section represent guidance for IHE Technical Framework authors who need to use web services in specific transactions. These requirements fall into two categories:
- Providing consistency and clarity in the IHE specifications.
- Affecting the wire format of the transactions.
When the requirements for particular text are specified, the following notation is used:
- curly braces (i.e., {}) are used to denote a part of a string which shall always be replaced with a string corresponding to the specific transaction, actor, or profile;
- square brackets (i.e., []) are used to denote a part of a string which shall be either replaced with a string corresponding to the specific transaction, or shall be completely omitted.
V.3.1 Requirements for Transactions using HL7 V3 Messages
When IHE transactions use HL7 V3 Messages, the Web Services protocol will conform to the HL7 Web Services Basic, Addressing, Security, and Reliable Messaging Profiles, with additional constraints as specified in the following sub-sections.
V.3.1.1 HL7 WS Basic Profile Constraints
The Sender and Receiver shall conform to the HL7 WS Basic Profile with five modifications. The first modification is the requirement of supporting SOAP 1.2, while the HL7 WS Basic Profile provides the choice of supporting either SOAP 1.1 or SOAP 1.2, or both.
The second modification is to HL7-WSP200, which recommends that a WSDL document describes a specific HL7 application role. For consistency with non-HL7 V3 transactions, IHE specifications shall provide an example WSDL document for all transactions of an actor per profile (see IHE-WSP200).
The third modification is to HL7-WSP201, which recommends that the HL7 Application Role ID is to be used as the name of the WSDL definition. For consistency with non-HL7 V3 transactions the name of the example WSDL definition provided in the IHE specification shall be the actor name of the transaction's receiver (see the IHE-WSP201).
The fourth modification is to HL7-WSP202, which specifies the use of the HL7 namespace as the target namespace of the WSDL document. This would prevent creating a single WSDL for actors which use both HL7 V3 and non-HL7 V3 IHE transactions (e.g., an XDS registry implementing the XDS.b Profile with the Patient Identity Feed HL7 V3 transaction). For consistency among all IHE transactions, when creating an IHE transaction specification, the WSDL target namespace shall be specified as “urn:ihe:<committee name>:<profile>:<year> (see IHE-WSP202).
The fifth modification is to HL7-WSP208, which specifies that “WSDL messages for Interactions SHOULD use wsdl:operation/wsdl:input/@wsa:Action = "urn:hl7-org:v3:{Interaction_Artifact_Id}”. IHE extends the “should” to support situations where one HL7 message is being used within two transactions for significantly different purposes. For this case the second use of the message shall extend the HL7 specified Action string with “:[transaction-name]” where [transaction-name] is the name of the second transaction.
V.3.1.2 HL7 WS Addressing Profile Constraints
The Sender and Receiver should conform to the HL7 WS Addressing Profile. No additional constraints are made in this sub-section.
V.3.1.3 HL7 WS Security Profile Constraints
IHE does not specify whether the Sender and Receiver should implement the HL7 WS Security Profile. The decision to implement the HL7 WS Security Profile is left to implementers. Each IHE transaction specifies its ATNA requirements for security and authentication. Security profiles such as Cross-Enterprise User Assertion (XUA) contain further security requirements. With the publication of WS-Security 1.1 and when the WS-I Basic Security Profile 1.1 is released, it is expected that ATNA (or a different profile) may incorporate additional options for Web Services, and the HL7 WS Security Profile will be incorporated in this appendix.
V.3.1.4 HL7 WS Reliable Messaging Profile Constraints
IHE does not specify whether the Sender and Receiver should implement the HL7 WS Reliable Messaging Profile. The decision to implement the HL7 WS Reliable Messaging Profile is left to implementers. When the WS-I Reliable Secure Profile Working Group releases a profile it is expected that additional options for Web Services may be added, and the HL7 WS Reliable Messaging Profile will be incorporated in this appendix.
V.3.2 Requirements for Transactions which don’t use HL7 V3 Messages
The following IHE web services requirements are derived from the HL7 Web Services Profile. This provides consistency among the IHE transactions, compatibility to existing Web Services implementations through the WS-I profiles, and a well-defined mechanism for adding additional layers of web services in the future. The HL7 Web Services Profile also provides detailed background regarding the requirements presented here.
The numbering scheme for the individual requirements uses the following convention:
- IHE-WS[P|A|S|RM]nnn[.e]) text
P, A, S, and RM represent the Basic, Addressing, Security, and Reliable Messaging requirements sections in this specification, nnn represents a unique number for this specification, and text is the text of the requirement. This directly corresponds to the convention used in the HL7 Web Services Profile, and for easier navigation, the same numbers correspond to the equivalent requirements in both specifications. Note that not all implementation decisions from the HL7 Web Services Profile are relevant for non-HL7 web services transactions. If there are cases where an IHE Web Services requirement exists that does not correspond to an implementation decision from the HL7 Web Services Profile, the optional extension to the number (shown as .e above) can be used to eliminate the possibility of confusion.
Table V.3.2-1: Web Services Requirements for Non-HL7 Transactions
| Requirement Identifier | Requirement text | SOAP message format affected? |
| IHE-WSP200 | Example WSDL documents shall implement a specific IHE actor within a specific IHE Integration Profile. | No |
| IHE-WSP201 | The attribute /wsdl:definitions/@name in the example WSDL document provided with an IHE specification shall be the name of the IHE actor providing the service. | No |
| IHE-WSP202 | The targetNamespace of the example WSDL shall be urn:ihe:{committee}:{profile}:{year} | No |
| IHE-WSP203 | The example WSDL shall include XML Schema Definition references for the transactions payloads. | No |
| IHE-WSP205 | Two WSDL messages shall be defined for a request-response transaction. | No |
| IHE-WSP206 | In the example WSDL provided by an IHE specification a single WSDL part named Body shall be defined for each WSDL message and the part type shall refer to an element defined in the Schema Definition required in IHE-WSP203. | Determines the format of the SOAP Body |
| IHE_WSP207 | For each input and output message defined in the WSDL portType operation an attribute wsaw:Action SHALL be included. | No |
| IHE_WSP208 |
WSDL operations SHALL use wsdl:operation/wsdl:input/@wsaw:Action = "urn:ihe:{committee}:{Year}:{Transaction name}[Operation]" and wsdl:operation/wsdl:output/@wsaw:Action = "urn:ihe:{committee}:{Year}:{Transaction name}[Operation]Response" |
Determines the SOAP header content for wsa:Action |
| IHE_WSP211 |
Operations defined in the WSDL portType may or may not have a wsoap12:operation/@soapAction attribute provided. If wsoap12:operation/@soapAction is not provided, wsoap12:operation/@soapActionRequired shall be false. SOAP message consumers shall ignore any soapAction value found in a SOAP message. |
Determines the value of soapAction |
| IHE_WSP212 |
The example WSDL provided with an IHE specification shall use the SOAP Binding described in WSDL 1.1 Chapter 3 and the binding extension for SOAP 1.2 . |
No |
| IHE_WSP215 | IHE transactions referencing the standards specified by Appendix V shall support SOAP 1.2, unless otherwise noted in the transaction. The example WSDL document provided with an IHE specification shall contain a SOAP 1.2 binding unless the transaction specifically notes that SOAP 1.2 is not supported. | Determines the namespace of the SOAP message |
| IHE_WSA100 | The example WSDL provided with IHE transactions shall use the WS-Addressing framework when specifying the Web Services protocol. | Determines the WSA content for the SOAP header |
| IHE_WSA101 | All <wsa:Action> elements shall have the mustUnderstand attribute set (mustUnderstand=”1” or “true”) | Ensures that web services frameworks are configured to properly generate and process WS-Addressing headers |
| IHE_WSA102 | The <wsa:ReplyTo> element of the initiating message shall be present. (See Note 1.) | Ensures that responses are routed to the appropriate web services end point, or as an immediate response |
Note 1: There may be web services toolkits which implement the WS-Addressing features improperly and may have problems processing a wsa:ReplyTo header with a mustUnderstand attribute set to true. Implementers of SOAP clients are advised to plan for mitigating the impact of toolkits with deficient implementation of WS-Addressing by putting the mustUnderstand attribute only on other header(s).
V.3.2.1 Basic Requirements
V.3.2.1.1 Naming conventions and namespaces
IHE-WSP200) Example WSDL documents shall implement a specific IHE actor within a specific IHE Integration Profile.
This editorial requirement means that if several IHE actors within a profile are combined, then separate WSDL documents for each actor need to be provided. This only applies to actors, which provide a particular service, i.e., the receivers in an IHE transaction.
IHE-WSP201) IHE requires the profile writers and recommends the implementers to use the following naming convention for WSDL artifacts.
- NAME – represents the formal IHE actor name of the actor providing the service with spaces omitted from the name (e.g., DocumentRegistry is the NAME value for the XDS.b Document Registry Actor). Specifically, NAME is the value of the /wsdl:definitions/@name attribute which will be specified for each transaction.
- Transaction Name – represents the formal IHE Transaction Name for this particular web-service exchange with spaces omitted from the name (e.g., RegistryStoredQuery is the TRANSACTION_for the XDS.b Registry Stored Query Transaction)
| WSDL Artifact | Proposed Naming |
| message request | {Transaction Name}_Message |
| message response | {Transaction Name}Response_Message |
| portType | {NAME}_PortType |
| Operation | {NAME}_{Transaction Name}[_OperationID] |
| SOAP 1.2 binding | {NAME}_Binding_Soap12 |
| SOAP 1.2 port | {NAME}_Port_Soap12 |
Here is an example of how the nomenclature is applied:
message request -> "RegistryStoredQuery_Message"
message response -> RegistryStoredQueryResponse_Message
portType -> "DocumentRegistry_PortType"
operation -> "DocumentRegistry_RegistryStoredQuery_Request"
SOAP 1.2 binding -> "DocumentRegistry_Binding_Soap12"
SOAP 1.2 port -> "DocumentRegistry_Port_Soap12"
IHE-WSP202)
IHE requires the use of the following naming convention for targetNamespace of example WSDL.
- DOMAIN – represents the acronym of the IHE domain who authored this web-service transaction (e.g., iti)
- PROFILE – represents the acronym of the IHE profile which references this web-service transaction (e.g., xds-b)
- YEAR – represents the four-digit year that this transaction was first published within a Trial Implementation profile
- TYPE – optional extension of which other IHE specifications already using XML namespaces may make use
The targetNamespace of the example WSDL shall be urn:ihe:{DOMAIN}:{PROFILE}:{YEAR} and may be extended to urn:ihe:{DOMAIN}:{PROFILE}:{YEAR}:{TYPE}.
As an example the namespace for the 2008 XDS.b Integration Profile is urn:ihe:iti:xds-b:2007
.
IHE-WSP203) The example WSDL shall include XML Schema Definition references for the transactions payloads.
The purpose of this requirement is to specify how authors of IHE profiles specify the transactions which use web services. This requires both the existence of an XML schema definition for the transaction payloads, and the manner in which it is specified in the WSDL file – by reference.
V.3.2.1.2 Message and portType Definitions
IHE-WSP205) Two WSDL messages shall be defined for a request-response transaction.
IHE-WSP206) In the example WSDL provided by an IHE specification a single WSDL part named Body shall be defined for each WSDL message and the part type shall refer to an element defined in the Schema Definition required in IHE-WSP203.
IHE-WSP207) For each input and output message defined in the WSDL portType operation an attribute wsaw:Action SHALL be included.
For compatibility with the Addressing requirements and consistency with naming across IHE Web Services implementations, the wsaw:Action attribute for each WSDL input and output message must be defined.
The wsaw:Action attribute shall be ignored by Web Services implementations that do not support WS-Addressing. It is very important to have the attribute in mixed cases where just one of the endpoints might support the WS-Addressing specification to avoid communication or routing errors.
IHE-WSP208) WSDL operations SHALL use wsdl:operation/wsdl:input/@wsaw:Action = "urn:ihe:{Domain}:{Year}:{Transaction name}" and wsdl:operation/wsdl:output/@wsaw:Action = "urn:ihe:{Domain}:{Year}:{Transaction name}Response"
For example, the wsaw:Action value for the Registry Stored Query [ITI-18] transaction is specified as “urn:ihe:iti:2007:RegistryStoredQuery” and “urn:ihe:iti:2007:RegistryStoredQueryResponse”.
V.3.2.1.3 Binding
Multiple WSDL bindings can be defined in order to support different protocols and transports. The naming is consistent with the naming rules specified in the previous section.
IHE-WSP211) Operations defined in the WSDL portType may or may not have a wsoap12:operation/@soapAction attribute provided. If wsoap12:operation/@soapAction is not provided, wsoap12:operation/@soapActionRequired shall be false.
SOAP message consumers shall ignore any soapAction value found in a SOAP message.
IHE-WSP212) The example WSDL provided with an IHE specification shall use the SOAP Binding described in WSDL 1.1 Chapter 3 and the binding extension for SOAP 1.2 .
IHE-WSP215) IHE transactions referencing the standards specified by Appendix V shall support SOAP 1.2, unless otherwise noted in the transaction. The example WSDL document provided with an IHE specification shall contain a SOAP 1.2 binding unless the transaction specifically notes that SOAP 1.2 is not supported.
SOAP 1.2 is the base standard for several WS specification, and has many available and easily accessible implementations.
Example 1: Example WSDL File with a Non-HL7 Transaction
<definitions xmlns:wsoap11="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ihe="urn:ihe:iti:xds-b:2007" xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0"
targetNamespace="urn:ihe:iti:xds-b:2007" xmlns:wsoap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:wsaw="http://www.w3.org/2007/05/addressing/wsdl" name="XDSRepository">
<documentation>IHE XDS Document Repository</documentation>
<types>
<xsd:schema elementFormDefault="qualified">
<xsd:import namespace="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0"
schemaLocation="../schema/ebXML_RS/rs.xsd"/>
<xsd:import namespace="urn:ihe:iti:xds-b:2007" schemaLocation="../schema/IHE/IHEXDS.xsd"/>
</xsd:schema>
</types>
<message name="RetrieveDocumentSet_Message">
<documentation>Retrieve Document Set</documentation>
<part name="body" element="ihe:RetrieveDocumentSetRequest"/>
</message>
<message name="RetrieveDocumentSetResponse_Message">
<documentation>Retrieve Document Set Response</documentation>
<part name="body" element="ihe:RetrieveDocumentSetResponse"/>
</message>
<message name="ProvideAndRegisterDocumentSet_Message">
<documentation>Provide and Register Document Set</documentation>
<part name="body" element="ihe:ProvideAndRegisterDocumentSetRequest"/>
</message>
<message name="ProvideAndRegisterDocumentSetResponse_Message">
<documentation>Provide And Register Document Set Response</documentation>
<part name="body" element="rs:RegistryResponse"/>
</message>
<portType name="XDSDocumentRepository_PortType">
<operation name="ProvideAndRegisterDocumentSet">
<input message="ihe:ProvideAndRegisterDocumentSet_Message"
wsaw:Action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"/>
<output message="ihe:ProvideAndRegisterDocumentSetResponse_Message"
wsaw:Action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse"/>
</operation>
<operation name="RetrieveDocumentSet">
<input message="ihe:RetrieveDocumentSet_Message"
wsaw:Action="urn:ihe:iti:2007:RetrieveDocumentSet"/>
<output message="ihe:RetrieveDocumentSetResponse_Message"
wsaw:Action="urn:ihe:iti:2007:RetrieveDocumentSetResponse"/>
</operation>
</portType>
<binding name="XDSDocumentRepository_Binding_Soap11" type="ihe:XDSDocumentRepository_PortType">
<wsoap11:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ProvideAndRegisterDocumentSet">
<wsoap11:operation soapAction="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"/>
<input>
<wsoap11:body use="literal"/>
</input>
<output>
<wsoap11:body use="literal"/>
</output>
</operation>
<operation name="RetrieveDocumentSet">
<wsoap11:operation soapAction="urn:ihe:iti:2007:RetrieveDocumentSet"/>
<input>
<wsoap11:body use="literal"/>
</input>
<output>
<wsoap11:body use="literal"/>
</output>
</operation>
</binding>
<binding name="XDSDocumentRepository_Binding_Soap12" type="ihe:XDSDocumentRepository_PortType">
<wsoap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ProvideAndRegisterDocumentSet">
<wsoap12:operation soapAction="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"/>
<input>
<wsoap12:body use="literal"/>
</input>
<output>
<wsoap12:body use="literal"/>
</output>
</operation>
<operation name="RetrieveDocumentSet">
<wsoap12:operation soapAction="urn:ihe:iti:2007:RetrieveDocumentSet"/>
<input>
<wsoap12:body use="literal"/>
</input>
<output>
<wsoap12:body use="literal"/>
</output>
</operation>
</binding>
<service name="XDSDocumentRepository_Service">
<port name="XDSDocumentRepository_Port_Soap11" binding="ihe:XDSDocumentRepository_Binding_Soap11">
<wsoap11:address location="http://servicelocation/XDSDocumentRepository_Service"/>
</port>
<port name="XDSDocumentRepository_Port_Soap12"
binding="ihe:XDSDocumentRepository_Binding_Soap12">
<wsoap12:address location="http://servicelocation/XDSDocumentRepository_Service"/>
</port>
</service>
</definitions>
V.3.2.2 Addressing Requirements
The Web Services Addressing specification (WS-Addressing) defines a framework for a transport-neutral SOAP messaging. Although understanding the concepts outlined in WS-Addressing is important, most of the underlying details will be shielded by the abstraction layers provided to developers. This specification assumes an abstract separation between the application layer, the Web services messaging infrastructure layer, and the message transport layer.
The IHE transaction is built at the application layer, it is passed to the Web services messaging infrastructure layer where the SOAP message is constructed according to the rules set in the WSDL. The action value specified in the WSDL is used to construct the <wsa:Action> SOAP header. The endpoint address specified in the WSDL (or the supplied end point reference) is used to construct the <wsa:To>. Depending on the message exchange pattern (e.g., one-way, request-response), other WS-Addressing headers may be added at this point (e.g., <wsa:From>, <wsa:ReplyTo>, etc.).
IHE-WSA100) The example WSDL provided with IHE transactions shall use the WS-Addressing framework when specifying the Web Services protocol.
IHE-WSA101) All <wsa:Action> elements shall have the mustUnderstand attribute set (mustUnderstand=”1” or “true”)
IHE-WSA102) The <wsa:ReplyTo> element of the initiating message shall be present.
Note: There may be web services toolkits which implement the WS-Addressing features improperly and may have problems processing a wsa:ReplyTo header with a mustUnderstand attribute set to true. Implementers of SOAP clients are advised to plan for mitigating the impact of toolkits with deficient implementation of WS-Addressing by putting the mustUnderstand attribute only on other header(s).
See Section V.9.2 for sample headers for Synchronous and Asynchronous messages.
V.3.2.3 Security Requirements
The IHE ATNA Profile contains requirements which address certain aspects of security and authentication, including HTTPS transport requirements. Individual transactions which use Web Services will incorporate these requirements depending on their needs. Security profiles such as Cross-Enterprise User Assertion (XUA) Profile contain further security requirements. With the publication of the WS-I Basic Security Profile it is expected that ATNA will incorporate additional options for Web Services, and this appendix will reflect any requirements specific for Web Services for IHE transactions.
V.4 Web Services for specific IHE Transactions
The Web Services specification is provided in three parts. The first part will be in Volumes 2, where a separate subsection shall be added for each affected IHE transaction at the end of the “Message Semantics” section. This subsection shall detail the types and message parts of the WSDL. The actor-specific constraints against the IHE Web Services Requirements specified above shall be added at the end of each “Expected Actions” section.
The second, informative part of the specification is online: see Appendix W which contains a complete WSDL (Web Services Description Language) description of the web service, which aggregates the snippets from Volume 2 described above. There will be one WSDL contract per actor per profile. Each transaction is represented by a port type, where the operations names and message names follow the requirements specified in Section V.3.2.1.1. The complete WSDL is for reference purposes for implementers.
V.5 Synchronous and Asynchronous Web Services Exchange
V.5.1 Overview
When two actors, later referred to as Requestor and Provider, need to exchange web services messages using a request-response message exchange pattern, they can do so synchronously or asynchronously.
With synchronous message exchange, the Requestor sends a request and blocks waiting for a response from the Provider. The Requestor receives the response on the same connection that the Requestor initially established to send the request. Synchronous exchange is usually easier to implement and requires that the Provider be available when the Requestor needs to send a request.
With asynchronous message exchange, the Requestor is only concerned with sending the request, knowing that it will ‘eventually’ receive a response. The Provider may not be available at the time the request is sent. When the Provider receives and processes the message it sends a response back to the Requestor over a new connection. Asynchronous Web Services Exchange enables support for network infrastructures where:
- Transports are unreliable
- Systems are not always available
- Variable or high communication latency is present
V.5.2 Considerations for using Asynchronous Web Services Exchange
Asynchronous Web Services Exchange opens the option for using intermediaries for store and forward or offline communication modes, and leveraging reliable messaging mechanisms to address the reliability and availability challenges that these types of network infrastructures present. Asynchronous Web Services Exchange enables support for clinical use cases that can benefit from asynchronous infrastructure capabilities such as offline mode.
Adding support for asynchronous exchange should take into consideration the fact that:
- The request and response messages are decoupled and transmitted on separate connections as shown in Figure V.5.2-1 below.
- The Requestor will ‘unblock’ before it receives the response. The response will be received asynchronously at a later time. Having decoupled request/response exchange should draw attention to the following:
- The Requestor should have response timeout capability to handle the case when a response has not been received within expected time interval
- The Requestor should be able to match request/response pairs
Figure V.5.2-1: Request and Response Messages
V.5.3 Specification of the use of Asynchronous Web Services Exchange
Volume 2 transaction specifications will identify whether asynchronous support is required or optional on the transaction level. If nothing is specified in Volume 2, only synchronous exchange is expected. When optional asynchronous support is applicable to a transaction, the profile specification in ITI TF-1 will identify that support as required for actors in that profile or as a named option.
V.6 Web Services Standards Evolution
As the industry acceptance of newer standards/newer versions of existing standards progresses, new options will be added to existing transactions. One such expected change is the support for WS-Security and WS-Reliable Messaging as new options to web services transactions.
V.7 Web Services References
WS-I: http://ws-i.org/
WS-I Basic Profile 1.2: http://ws-i.org/Profiles/BasicProfile-1.2-2010-11-09.html
WS-I Basic Profile 2.0: http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html
SOAP 1.2: http://www.w3.org/TR/soap12-part0/
WSDL 1.1 SOAP 1.2 binding: http://www.w3.org/Submission/wsdl11soap12/
HL7 V3 Web Services Profile: http://www.hl7.org/v3ballot/html/infrastructure/transport/transport-wsprofiles.htm
WS-Addressing: http://www.w3.org/TR/ws-addr-core
WS-I Basic Security Profile 1.1: http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html
WS-I Reliable Secure Profile: http://www.ws-i.org/Profiles/ReliableSecureProfile-1.0-2010-11-09.html
MTOM: http://www.w3.org/TR/soap12-mtom/
XOP: http://www.w3.org/TR/xop10/
WS-Security 1.0: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss#technical
WS-Security 1.1: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss#technical
WS-Secure Conversation: http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/ws-secureconversation.html
WS-Trust: http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/errata01/os/ws-trust-1.4-errata01-os-complete.html
WS-Policy: http://www.w3.org/TR/ws-policy/
WS-Reliable Messaging: http://docs.oasis-open.org/ws-rx/wsrm/200702
V.8 Usage of MTOM/XOP
See Section V.9 for sample messages.
V.8.1 Simple SOAP vs MTOM
A simple SOAP message contains the SOAP xml as the message body. An MTOM-encoded message contains a MIME Multipart message with the SOAP xml as the body of one of the parts.
Unless a transaction specifies otherwise, Simple SOAP shall be used. Both the request and the response messages shall use the same encoding.
V.8.2 Use of MTOM encoding
Transactions making use of MTOM shall conform to http://www.w3.org/TR/soap12-mtom and http://www.w3.org/TR/xop10/.
Actors that create messages with xsi:base64Binary content may use XOP Optimization to reduce the size of the message. If there are multiple xsi:base64Binary content elements, the actor may optimize none, any or all of them at its discretion. Typically, small content will be left in the XML Infoset while larger content will be "optimized". Note that regardless of whether any binary elements are optimized, or even present, the overall message must still be formatted as MTOM/XOP.
Actors that receive MTOM messages shall be capable of accepting any content of type xsi:base64Binary whether it is contained in the XML Infoset or serialized as Optimized Content.
See the following sections of the XOP specification for more information:
- https://www.w3.org/TR/2005/REC-xop10-20050125/#introduction (Introduction)
- https://www.w3.org/TR/2005/REC-xop10-20050125/#terminology (Terminology)
- https://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages (Creating XOP Packages).
- https://www.w3.org/TR/2005/REC-xop10-20050125/#interpreting_xop_packages (Interpreting XOP Packages).
V.8.3 Use of XOP Optimization (Informative)
In order to optimize a specific piece of binary data:
- Create an additional MIME part in the enclosing MTOM message.
- Assign the new MIME part a Content-ID header containing a unique identifier surrounded by <> angle brackets.
- Place the Optimized Content in the body of the new MIME part.
- Replace the Optimized Content with an <xop:Include> element. The @href attribute of the element is the string “cid:” followed by the Content-ID header of the corresponding MIME part (without the <> brackets)
Note that reconstruction of XOP-encoded messages must render them identical to the original in terms of the XML Infoset, in order to be able to calculate matching digital signatures (see http://www.w3.org/TR/xop10/#xop_processing_model). As such, only canonical data may be XOP-optimized and XOP-optimized items should be reconstructed to canonical xsi:base64Binary form (see http://www.w3.org/TR/xmlschema-2/#base64Binary for a description of the canonical form).
V.9 Sample SOAP Messages
Because there are so many different ways to construct SOAP messages, the samples in this section show the building blocks typically used for SOAP requests and their relative SOAP responses. A sample combining many of the building blocks is included in Section V.9.4.
Namespace declarations (see Table V.2.4-1) are omitted for brevity.
V.9.1 Simple SOAP
<?xml version='1.0' encoding='UTF-8'?>
<soap12:Envelope>
<soap12:Header>
<!-- SOAP Headers go here -->
</soap12:Header>
<soap12:Body>
<!-- SOAP Body goes here -->
</soap12:Body>
</soap12:Envelope>
V.9.2 SOAP Headers
The sample headers show the WS-Addressing headers <wsa:Action/>, <wsa:MessageID/>, <wsa:ReplyTo/>, etc. These WS-Addressing headers are populated according to Appendix V: Web Services for IHE Transactions and according to the specific ITI transaction.
V.9.2.1 Headers for Synchronous Request
<soap12:Header>
<wsa:To>http://localhost:4040/axis2/services/test11966a</wsa:To>
<wsa:MessageID>urn:uuid:76A2C3D9BCD3AECFF31217932910053</wsa:MessageID>
<wsa:Action soap12:mustUnderstand="1">
urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b
</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>
http://www.w3.org/2005/08/addressing/anonymous
</wsa:Address>
</wsa:ReplyTo>
</soap12:Header>
V.9.2.2 Headers for Synchronous Response
<soap12:Header>
<wsa:Action soap12:mustUnderstand="1">
urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse
</wsa:Action>
<wsa:RelatesTo>urn:uuid:6d296e90-e5dc-43d0-b455-7c1f3eb35d83</wsa:RelatesTo>
</soap12:Header>
V.9.2.3 Headers for Asynchronous Request
<soap12:Header>
<wsa:Action soap12:mustUnderstand="1">
urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b
</wsa:Action>
<wsa:MessageID>urn:uuid:6d296e90-e5dc-43d0-b455-7c1f3eb35d83</wsa:MessageID>
<wsa:ReplyTo soap12:mustUnderstand="1">
<wsa:Address>
http://192.168.2.4:9080/XdsService/DocumentSourceReceiver.svc
</wsa:Address>
</wsa:ReplyTo>
<wsa:To soap12:mustUnderstand="1">
http://localhost:2647/XdsService/DocumentRepositoryReceiver.svc
</wsa:To>
</soap12:Header>
V.9.2.4 Headers for Asynchronous Response
<soap12:Header>
<wsa:Action soap12:mustUnderstand="1">
urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse
</wsa:Action>
<wsa:MessageID>urn:uuid:D6C21225-8E7B-454E-9750-821622C099DB</wsa:MessageID>
<wsa:RelatesTo>urn:uuid:6d296e90-e5dc-43d0-b455-7c1f3eb35d83</wsa:RelatesTo>
<wsa:To soap12:mustUnderstand="1">
http://localhost:2647/XdsService/DocumentSourceReceiver.svc
</wsa:To>
</soap12:Header>
V.9.3 MTOM/XOP
HTTP headers are included in this sample to reflect the HTTP Binding included in the MTOM specification.
V.9.3.1 No XOP Optimized Content
POST /axis2/services/repository HTTP/1.1
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180;
type="application/xop+xml"; start="<0.urn:uuid76A2C3D9BCD3AECFF31217932910181@apache.org>";
start-info="application/soap+xml"; action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"
User-Agent: Axis2
Host: localhost:4040
Content-Length: 4567
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org>
<!-- The soap12:Envelope has the same content as Simple SOAP -->
<?xml version='1.0' encoding='UTF-8'?>
<soap12:Envelope>
<soap12:Header>
<!-- SOAP Headers go here -->
</soap12:Header>
<soap12:Body>
<!-- Other parts of SOAP body omitted -->
<xds:Document id="id1">
<!-- Example of un-optimized content. NOTE: The content is shown indented for
readability. For XOP optimized content to be allowed, however, no whitespace
is permitted before, inline or after the content. -->
SGVyZSBpcyB0aGUgZG9jdW1lbnQgY29udGVudA==
</xds:Document>
</soap12:Body>
</soap12:Envelope>
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
V.9.3.2 XOP Optimized Content
POST /axis2/services/repository HTTP/1.1
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180;
type="application/xop+xml"; start="<0.urn:uuid76A2C3D9BCD3AECFF31217932910181@apache.org>";
start-info="application/soap+xml"; action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"
User-Agent: Axis2
Host: localhost:4040
Content-Length: 4567
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org>
<!-- The soap12:Envelope has the same content as Simple SOAP, except for the optimized
content -->
<?xml version='1.0' encoding='UTF-8'?>
<soap12:Envelope>
<soap12:Header>
<!-- SOAP Headers go here -->
</soap12:Header>
<soap12:Body>
<!-- Other parts of SOAP body omitted -->
<xds:Document id="id1">
<!-- Example of XOP optimized content. NOTE: xop:Include is shown indented for
readability. In practice, no whitespace is allowed before or
after the element. -->
<xop:Include href="cid:1.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org">
</xds:Document>
</soap12:Body>
</soap12:Envelope>
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
Content-Type: text/plain; charset=UTF-8"
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org>
Here is the document content
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180--
V.9.4 Full Sample
This sample combines several of the building blocks from the previous sections to show a Synchronous Request that uses MTOM/XOP with optimized content.
POST /axis2/services/repository HTTP/1.1
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180;
type="application/xop+xml"; start="<0.urn:uuid76A2C3D9BCD3AECFF31217932910181@apache.org>";
start-info="application/soap+xml"; action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"
User-Agent: Axis2
Host: localhost:4040
Content-Length: 4567
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org>
<?xml version='1.0' encoding='UTF-8'?>
<soap12:Envelope>
<soap12:Header>
<wsa:To>http://localhost:4040/axis2/services/test11966a</wsa:To>
<wsa:MessageID>urn:uuid:76A2C3D9BCD3AECFF31217932910053</wsa:MessageID>
<wsa:Action soap12:mustUnderstand="1">
urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b
</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>
http://www.w3.org/2005/08/addressing/anonymous
</wsa:Address>
</wsa:ReplyTo>
</soap12:Header>
<soap12:Body>
<!-- Other parts of SOAP body omitted -->
<xds:Document id="id1">
<xop:Include href="cid:1.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org">
</xds:Document>
</soap12:Body>
</soap12:Envelope>
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180
Content-Type: text/plain; charset=UTF-8"
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:76A2C3D9BCD3AECFF31217932910181@apache.org>
Here is the document content
--MIMEBoundaryurn_uuid_76A2C3D9BCD3AECFF31217932910180--