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.
|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.|
Each operation has one or more input and output parameters:
|echoBack||Input||String||Data to be sent back by the connectivity test.|
|Return||Output||String||Data sent back by the test.|
|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.
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:
- UnsupportedOperationFault_Message – generated if the sender attempts to request an operation that is not part of the IIS SOAP Web Service.
- SecurityFault_Message – generated if the authentication credentials supplied in the submitSingleMessage operation are not validated.
- 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.
- 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
|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.
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.
See SOAP Web Services for additional implementation resources.
Images and logos on this website which are trademarked/copyrighted or used with permission of the trademark/copyright or logo holder are not in the public domain. These images and logos have been licensed for or used with permission in the materials provided on this website. The materials in the form presented on this website may be used without seeking further permission. Any other use of trademarked/copyrighted images or logos requires permission from the trademark/copyright holder...more
This graphic notice means that you are leaving an HHS Web site. For more information, please see the Exit Notification and Disclaimer policy.