Skip directly to search Skip directly to A to Z list Skip directly to navigation Skip directly to page options Skip directly to site content

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.


connectivityTestTo test connectivity; to verify that the SOAP Web Service is accessible.
submitSingleMessageTo submit an HL7 version 2.3.1 or 2.5.1 message to an IIS.



Each operation has one or more input and output parameters:

Operation: connectivityTest


ParameterInput/OutputData typeDescription
echoBackInputStringData to be sent back by the connectivity test.
ReturnOutputStringData sent back by the test.


Operation: submitSingleMessage


ParameterInput/OutputData typeDescription
usernameInputStringIIS username
passwordInputStringIIS password
facilityIDInputStringIIS Facility ID
hl7MessageInputStringHL7 version 2.3.1 or 2.5.1 message intended for IIS
ReturnOutputStringHL7 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


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

ParameterInput/OutputData typeDescription
CodeOutputIntegerSOAP Fault code number, intended for automated use by client software to identify the fault.
ReasonOutputStringSOAP Fault reason, intended to be a human-readable explanation of the error that caused the fault.
DetailOutputStringDetailed 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 [4 pages]

See SOAP Web Services for additional implementation resources.

 Top of Page