SOAP Standard Interface: Web Services Definition Language (WSDL)

The standard interface defines the contract between the trading partners (Sender and Receiver). SOAP (Simple Object Access Protocol) web services use a Web Services Definition Language (WSDL) to achieve this. It is a machine-readable contract detailing how the two trading partners will communicate.

The panel acknowledges asynchronous and/or batch processing still has its place in interoperability and is easily accomplished from a technical standpoint using SOAP. However, there is no need to replace processes that are already working well. As a result, the panel is focusing its work on the immediate need to define a national standard interface for synchronous transmissions of HL7 messages. If there is a demonstrated need for a national standard interface for asynchronous processing as well, the panel will engage the interested parties and address the need through a consensus-based approach. The first iteration of the standard WSDL is very straightforward and allows for single MSH messaging in a synchronous environment. The two operations in the standard WSDL are defined below.

Operation

Operation	Purpose
connectivityTest	To test connectivity; to verify that the SOAP Web Service is accessible.
submitSingleMessage	To submit an HL7 version 2.3.1 or 2.5.1 message to an IIS.

 

Parameters

Each operation has one or more input and output parameters:

Operation: connectivityTest

connectivityTest

Parameter	Input/Output	Data type	Description
echoBack	Input	String	Data to be sent back by the connectivity test.
Return	Output	String	Data sent back by the test.

 

Operation: submitSingleMessage

submitSingleMessage

Parameter	Input/Output	Data type	Description
username	Input	String	IIS username
password	Input	String	IIS password
facilityID	Input	String	IIS Facility ID
Hl7Message	Input	String	HL7 version 2.3.1 or 2.5.1 message intended for IIS
Return	Output	String	HL7 version 2.3.1 or 2.5.1 response from IIS

 

The username, password, and facilityID parameters are not required and may be null if the receiving IIS allows it. These parameters, if used, should be defined by the IIS and provided to the sender prior to initiating HL7 transmissions.

The Hl7Message and return parameters must contain the appropriate HL7 message as defined by the Implementation Guide for Immunization Data Transactions using Version 2.3.1 (or 2.5.1) of the Health Level Seven (HL7) Standard Protocol, and any local IIS HL7 implementation guides.

Top of Page

Faults

The SOAP Fault element is used to indicate error messages related to the SOAP operations and to carry detailed information within a SOAP message regarding the error.

There are four types of SOAP Faults in the IIS SOAP Web Service:

1. UnsupportedOperationFault_Message – generated if the sender attempts to request an operation that is not part of the IIS SOAP Web Service (See Section 4.3).
2. SecurityFault_Message – generated if the authentication credentials supplied in the submitSingleMessage operation are not validated.
3. MessageTooLargeFault_Message – generated if the Hl7Message parameter of the submitSingleMessage operation is too large. The maximum length should be specified by the IIS and provided to the sender prior to initiating HL7 transmissions.
4. UnknownFault_Message – Any SOAP fault that does not fit into one of the above three SOAP Fault categories will be returned as an "unknown" fault.

Each type of SOAP Fault contains the following parameters:

SOAP Fault parameters

Parameter	Input/Output	Data type	Description
Code	Output	Integer	SOAP Fault code number, intended for automated use by client software to identify the fault.
Reason	Output	String	SOAP Fault reason, intended to be a human-readable explanation of the error that caused the fault.
Detail	Output	String	Detailed explanation of fault.

 

Fault code numbers should be specified by the IIS and provided to the sender prior to initiating HL7 transmissions.

Standard WSDL

The WSDL below is the standard WSDL defined by the Transport Layer Expert Panel. This template WSDL must be modified by each IIS to reflect their environment correctly.

Standard WSDL Defined by Transport Layer Expert Panel [48 KB, 4 pages]

See SOAP Web Services for additional implementation resources.

Top of Page