WSDL, or Web Service Description Language, is an XML-based language used to define web services. The HL7 WSDL extensibility elements are used to construct HL7 messages by specifying the message parts, message formats, and other message related information used to properly map an HL7 message exchange. The HL7 WSDL elements also contain information that the HL7 Binding Component uses to establish connections and sessions with HL7 external systems. Various properties that affect the delivery of HL7 messages are included within the HL7 WSDL extensibility elements.
WSDL files are created using the WSDL Wizard and validated within the NetBeans IDE. The extensibility elements correspond to the properties you specify in the wizard. They are described here so you can add and modify them in the WSDL file directly.
For more information on how to use the WSDL Wizard to create and HL7 WSDL file see Using the HL7 Binding Component Wizard.
HL7 extensibility elements are divided into two sets of configuration elements:
Service Level elements are used to configure the connectivity and protocol. The Service Level extensibility elements are:
Binding Level elements are used to binding abstract WSDL messages to HL7 messages. The Binding Level extensibility elements are:
The following sections describe the HL7 extensibility elements. The tables describe the attributes for each extensibility element and its child elements. For each attribute or element the table lists the name, description, whether the attribute or element applies to both provider or consumer (Common), whether it is required, and an example of its usage.
You can add HL7 extensibility elements from the wizard when you create the WSDL file. After the WSDL file is created, you can add extensibility attributes by entering the text directly or graphically in the WSDL Editor
Open the HL7 Binding WSDL file in the WSDL Editor and expand the Services -> hl7wsdlService -> hl7wsdlPort nodes.
If the type of element you want to add (address, protocolproperties, or communicationcontrols) does not appear in the list, right-click the hl7wsdlPort node, point to Add and then select the type of element to add.
A new node is added under the hl7wsdlPort node.
To add an address element, do the following:
Right-click the hl7wsdlPort node, point to Add and then select HL7 Address.
A new hl7:address element appears in the list.
Right-click the new element and then select Properties.
Configure the address extensibility attributes, and then click Close.
For more information about these attributes, see HL7 address Element.
To add a protocolproperties element, do the following:
Right-click the hl7wsdlPort node, point to Add and then select HL7 Protocol Properties.
A new hl7:protocolproperties element appears in the list.
Right-click the new element and then select Properties.
Configure the protocolproperties extensibility attributes, and then click Close.
For more information about these attributes, see HL7 protocolproperties Element.
To add communicationcontrol attributes, do the following:
If the communicationcontrol element does not appear in the list, right-click the hl7wsdlPort node, point to Add and then select HL7 Communication Control.
A new hl7:communcationcontrols element appears in the list.
Right-click the hl7:communicationcontrols node and then select Add communicationcontrol.
A new hl7:communicationcontrol is added under the hl7:communicationcontrols node.
Right-click the new element and then select Properties.
Configure the communcationcontrol extensibility attributes, and then click Close.
Configure the following attribute properties. For more information about these attributes, see HL7 communicationcontrols Element.
name: Specifies the attribute.
value: Specifies the value associated with that attribute.
enabled: Specifies if the attribute is enabled.
recourseAction: Specifies the recourse action associated with the attribute.
The recourse actions are:
Reset: Closes the connection with the HL7 external system and throws an alert.
Resend: Resends the last sent message to the HL7 external system.
Suspend: Closes the connection with the HL7 external system, suspends the endpoint from processing the messages, and throws an alert.
Skipmessage: Remains connected but writes the message to an error queue.
Error: Throws an Exception.
The following tables list and describe the Service Level HL7 extensibility elements:
The HL7 address extensibility element specifies the information for connectivity to the HL7 external system.
Table 3 HL7 address Element Attributes
Name and Description |
Required or Optional |
Applies to Provider or Consumer |
Example |
---|---|---|---|
location: Specifies the host and port used to connect to the HL7 external system. |
Required |
Common (both) |
hl7://myhost:4040 |
transportProtocolName: Specifies the transport protocol used to transfer the message payload. |
Required |
Common (both) |
tcp-ip |
The following example illustrates the use of the HL7 address element defined for a service port.
<service name="SomeService"> <port name="port1" binding="tns:someBinding"> <hl7:address location="hl7://localhost:4040" transportProtocolName="tcp-ip"/> </port> </service> |
The HL7 protocolproperties extensibility element specifies the protocol specific information for connecting to the HL7 external system.
Table 4 HL7 protocolproperties Element Attributes
Name and Description |
Required or Optional |
Applies to Provider or Consumer |
Example |
---|---|---|---|
acknowledgeMode: Indicates the acknowledge mode type: Original Mode or Enhanced Mode. |
Optional |
Common (both) |
original |
llpType: Indicates the Lower Layer Protocol Type. MLLPv1, MLLPv2, or HLLP. |
Optional |
Common (both) |
MLLPv1 |
startBlockCharacter: Indicates the Start Block Character Value in a decimal ASCII number from 1 to 127. Unless there is a conflict, the value should be ASCII VT, which is decimal 11. |
Optional |
Common (both) |
11 |
endDataCharacter: Indicates the End Data Character Value in decimal ASCII number from 1 to 127. Unless there is a conflict, the value should be ASCII VT, which is decimal 28. |
Optional |
Common (both) |
28 |
endBlockCharacter: Indicates the End Block Character Value in decimal ASCII number from 1 to 127. To be strictly comply with the HL7 standard, this parameter must be set to a carriage Return, which is decimal 13. |
Optional |
Common (both) |
13 |
hllpChecksumenabled: Specifies if HLLP CheckSum is enabled. “true” indicates enabled. |
Optional |
Common (both) |
false |
seqNumberEnabled: Specifies if sequence number protocol is enabled. “true” indicates enabled. |
Optional |
Common (both) |
false |
validateMSH: Specifies if the MSH segment in the HL7 message is validated against initiation rules. “true” indicates enabled. |
Optional |
Common (both) |
false |
processingID: Specifies the ProcessingID value against which the MSH-11-ProcessingID field in the received message is validated when validateMSH is set to “true”. Valid values are P (production), D (debugging), or T (training). |
Optional |
Common (both) |
P |
versionID: Specifies the versionID value against which MSH-12-VersionID field in the received message is validated when validateMSH is set to true. Valid values are 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1 or 2.6. |
Required |
Common (both) |
2.3.1 |
fieldSeparator: Defines the Field Separator character value in a decimal ASCII number. This represents the separator between the segment ID and the first field, MSH-2-encoding characters. As such, it server as the separator and defines the character to be used as a separator for the rest of the message. The default setting is 124 which is the character "|". The allowed range is 1 to 127. This attribute value is used in creating the NAK for invalid HL7 messages. |
Optional |
Common (both) |
124 |
encodingCharacters: Specifies the encoding characters to be used in creating the NAK for invalid HL7 messages. This attribute contains the four characters in the following order: the component separator, repetition separator, escape character, and subcomponent separator. Recommended values are ^~\& (that is, ASCII 94, 126, 92, and 38, respectively). |
Optional |
Common (both) |
^~\& |
sendingApplication: Specifies the MSH-03 Sending Application to be used in creating the NAK for invalid HL7 messages. |
Optional |
Common (both) |
GlassFish ESB HL7 BC |
sendingFacility: Specifies the MSH-04 Sending Facility to be used in creating the NAK for invalid HL7 messages. |
Optional |
Common (both) |
GlassFish ESB HL7 BC |
enabledSFT: Enables or disables SFT segment processing. “true” indicates enabled. |
Optional |
Common (both) |
true |
softwareVendorOrganization: Specifies HL7 segment SFT-01, the software vendor organization field. This identifies the vendor who is responsible for maintaining the application. |
Optional |
Common (both) |
Sun Microsystems, Inc. |
softwareCertifiedVersionOr ReleaseNumber: Specifies HL7 segment SFT-02, the software certified version or release number. This is the current version or release number of the sending application. |
Optional |
Common (both) |
2.0 |
softwareProductName: Specifies HL7 segment SFT-03, the name of the software product that submitted the transaction. The product name is a key component in identifying the sending application. |
Optional |
Common (both) |
GlassFish ESB HL7 Binding Component |
softwareBinaryID: Specifies HL7 segment SFT-04, the software binary ID. This property is available for HL7 version 2.5 and above. Software binary IDs are issued by a vendor for each unique software version instance. Binary IDs are used to differentiate between differing versions of the same software. Identical primary IDs indicate that the software is identical at the binary level, but configuration settings may differ. |
Optional |
Common (both) |
2.0 |
softwareProductInformation: Specifies HL7 segment SFT-05, software product identification information. This can include a description of the software application, configuration settings, and software modifications. |
Optional |
Common (both) |
Binding Component for HL7 over TCP/IP connection |
softwareInstallDate: Specifies HL7 segment SFT-06, the software install date. This is the date on which the submitting software was installed at the sending site. Format as follows: YYYYMMDDHHSS. |
Optional |
Common (both) |
200909141020 |
journalingEnabled: Enables or disables journaling. If enabled, it stores the HL7 messages and respective ACK in the flat file database. “true” indicates enabled. |
Optional |
Common (both) |
true |
The following example illustrates the use of the HL7 protocolproperties element.
<hl7:protocolproperties acknowledgmentMode="original" llpType="MLLPv1" startBlockCharacter="11" endDataCharacter="28" endBlockCharacter="13" hllpChecksumEnabled="false" seqNumEnabled="false" processingID="P" versionID="2.3.1" validateMSH="false" sendingApplication="Sun Open ESB HL7 BC" sendingFacility="Sun Open ESB HL7 BC" enabledSFT="false" softwareVendorOrganization="Sun Microsystems, Inc" softwareCertifiedVersionOrReleaseNumber="2.0" softwareProductName="Sun Open ESB HL7 Binding Component" softwareBinaryID="2.0" softwareProductInformation="It is a binding component for HL7 over TCP/IP connection" journallingEnabled="false" mllpv2RetriesCountOnNak="0" mllpv2RetryInterval="0" mllpv2TimeToWaitForAckNak="0" encodingCharacters="^~&" softwareInstallDate="" fieldSeparator="124"/> |
HL7 Communication controls and recourse actions together control the data transfer over a TCP/IP connection. The configuration of these elements is defined inside the HL7 communicationcontrol extensibility element. These attributes help to establish Quality of Service (QoS) between HL7 external systems and HL7 endpoints.
The HL7 communication control attributes can be added to an endpoint from the WSDL Editor or from the Communication Controls. The HL7 communicationcontrol attributes differ for inbound or outbound endpoints.
Table 5 HL7 communicationcontrol Element Attributes
Name and Description |
Inbound or Outbound |
Recourse Action |
---|---|---|
MAX_NAK_SENT: Specifies the maximum number of NAKs, the binding component sends to the client before executing the recourse action. A negative acknowledgment is sent from the HL7 inbound endpoint when the received message from client is invalid. An invalid message, according to the HL7 specification, is one that fails MSH segment validation or has an invalid sequence number. |
Inbound |
Suspend and Reset. |
MAX_CANNED_NAK_SENT: Specifies the maximum number of canned NAKs, the binding component sends to the client before executing the configured recourse action. This communication control deals with the case where the message received from client is invalid as per the HL7 specification rules for that particular message. |
Inbound |
Suspend and Reset. |
MAX_CONNECT_RETRIES: Specifies the maximum number of connection retires the binding component will attempt before executing the recourse action. The value is presented in the format: n1;n2,n1;n2,..., where n1 is the number of retry attempts to connect, and n2 is the interval (in seconds) between retry attempts. If the value of n1 is –1, it indicates that the number of retry attempts is indefinite. |
Outbound |
Suspend and Error. |
TIME_TO_WAIT_FOR_A_RESPONSE: Specifies the amount of time (in seconds) that the binding component waits for a response from the external system before executing the configured recourse action. |
Outbound |
Resend, Reset, and Suspend. |
MAX_NO_RESPONSE: Specifies the maximum number of timeouts the binding component allows, while waiting for the response from external HL7 system, before executing the configured recourse action. This Communication Control is used in relationship with TIME_TO_WAIT_FOR_A_RESPONSE. The binding component resends the last sent message for each timeout until the configured maximum number of timeouts is exceeded. |
Outbound |
Suspend and Reset. |
MAX_RECEIVED: Specifies which recourse action the binding component will implement upon receiving a NAK from external system. There is no set value for this property other than enable and the selected recourse action. |
Outbound |
Resend, Reset, and Skipmessage. |
MAX_NAK_RECEIVED: Specifies the maximum number of NAKs (negative acknowledgments) that the binding component accepts before it executes the configured recourse action. |
Outbound |
Suspend, Reset, and Skipmessage. |
The HL7 extensibility elements used to bind abstract WSDL messages to HL7 messages fall into three element types. Each type signifies how the binding occurs. At the binding level, the configuration applies to the entire port type. At the operation level, the configuration applies only to the operation. At the message level, the configuration applies to that particular message, whether it's input or output.
The HL7 binding extensibility element specifies a binding that is of interest to the HL7 Binding Component. It is essentially an empty element that serves as a marker, allowing the HL7 Binding Component to gather HL7 "binding" information described by the other HL7 extensibility elements. The HL7 binding extensibility element must be specified in the WSDL to define an HL7 protocol based binding.
The following example demonstrates how the HL7 binding extensibility element is used to associate a binding with a specific HL7 protocol.
<binding name="someBinding" type="tns:somePortType"> <hl7:binding/> </binding> |
The HL7 operation extensibility element specifies an operation binding that is of interest to the HL7 Binding Component.
The following example demonstrates how the HL7 operation extensibility element is used to associate an abstract operation with an HL7 operation.
<binding name="someBinding" type="tns:somePortType"> <hl7:binding/> <operation name="someOperation"> </hl7:operation/> </binding> |
The HL7 message element specifies the concrete properties associated with receiving or sending an HL7 message from or to the HL7 external system. To configure the attributes, right-click the message element and then select Properties.
Table 6 HL7 message Element Attributes
Name and Description |
Required or Optional |
Applies to Provider or Consumer |
Example |
---|---|---|---|
use: Specifies if the message (part) defined is encoded using a well defined encoding style. |
Required |
Common (both) |
encoded |
encodingStyle: Specifies the encoding type associated with the message (part). This also defines the encoder type used to process the encoded data. |
Optional |
Common (both) |
hl7encoder-1.0 |
part:Indicates the part of the message that contains the HL7 message to be sent. |
Optional |
Common (both) |
part1 |
The following example demonstrates the HL7 message extensibility element defined for one-way operation.
<binding name="someBinding" type="tns:somePortType"> <hl7:binding/> <operation name="oneWayOp"> <hl7:operation/> <input> <hl7:message part="part1" use="encoded" encodingStyle="hl7encoder-1.0"/> </input> </operation> </binding> |