Using the HL7 Binding Component

Using the HL7 Binding Component Wizard

The HL7 Binding Component is similar to other binding components in that you use a wizard that steps you through creating the binding WSDL document. Each of these processes bring you to the HL7 Binding Component Wizard.

Note –

There are two types of WSDL documents. The Concrete WSDL Document option is the only way to create an HL7 Binding Component.

Abstract WSDL Document: An XML document that contains interface information that defines the structure of the method input properties, returned output types, exceptions or fault types, and the port type or interface. It does not contain any concrete data structures such as transport protocols or network address locations. The abstract type only requires that you fill out the Abstract Configuration page of the wizard.
Concrete WSDL Document:An XML document that includes the bindings to protocols, concrete address locations and service elements, along with the abstract WSDL information. The concrete type requires you to select a Binding and a Binding Type. Additional configuration pages are added to the wizard, associated with the binding and type you select, in this case, the HL7 Binding.

The following topics provide information and instructions for accessing and using the HL7 Binding Component Wizard:

Accessing the HL7 Binding Component Wizard

You can access the HL7 Binding Component Wizard and create an HL7 binding by performing any of the following procedures.

To Access the Wizard by Creating a New File

Select your project in the NetBeans IDE Projects window, then click the New File icon, or select File -> New File from the NetBeans menu.

Ctrl+N also opens the New File Wizard.

Select ESB as the Category, and select Binding as the File Type.

Click Next.

The Name and Location window appears.

Enter a name for the BC, select HL7 in the Binding field, and select the type of HL7 binding in the Type field (inbound or outbound).

If necessary, you can also modify the Folder and Target Namespace fields.

The target namespace is the URL String used as the target namespace.

Continue to Configuring the HL7 Binding Component in the Wizard.

To Access the Wizard by Creating a New Binding

Right-click your project in the Projects tree, and select New -> Other.

The New File Wizard appears.

Select ESB as the Category, and Binding as the File Type.

Click Next.

The Name and Location window appears.

Enter a name for the BC, select HL7 in the Binding field, and select the type of HL7 binding in the Type field (inbound or outbound).

If necessary, you can also modify the Folder and Target Namespace fields.

The target namespace is the URL String used as the target namespace.

Continue to Configuring the HL7 Binding Component in the Wizard.

To Access the Wizard by Creating a New WSDL Document

Right-click your project in the Projects tree, and select New -> WSDL Document.

The New WSDL Document Wizard appears.

Enter a File Name, and select Concrete WSDL Document as the WSDL Type.

This adds additional options to the wizard.

In the Binding field, select HL7; and in the Type field, select the type of HL7 Binding you want to create (inbound or outbound).

If necessary, you can also modify the Folder and Target Namespace fields.

The target namespace is the URL String used as the target namespace.

Continue to Configuring the HL7 Binding Component in the Wizard.

Configuring the HL7 Binding Component in the Wizard

From the HL7 Binding Component Wizard you can configure an inbound or outbound HL7 Binding Component. The HL7 Binding Component supports the following types of binding:

Inbound Request: A request message and MSH.9 field type, and inbound communication controls.
Inbound Request Reply: A request message and MSH.9 field type, response message, and inbound communication controls.
Outbound Request: A request message and outbound communication controls.
Outbound Request Reply: A request message, a response message, and outbound communication controls.

The Image shows the HL7 Binding Component Wizard.

To Configure the HL7 Binding Component in the Wizard

Complete one of the procedures under Accessing the HL7 Binding Component Wizard.

You should now be on the Name and Location window of the New WSDL Document Wizard, shown above.

Click Next.

The Abstract WSDL Details window appears.

Do one of the following:
- To implement an inbound or outbound request operation, select Add One-Way Operation.
- To implement an inbound or outbound request response operation, select Add Two-Way Operation.
The fields to configure the type of operation you chose appear.

Fill in the abstract WSDL properties as described in Abstract WSDL Properties.

Click Next.

The General Settings windows appears.

Note –
The image above shows the properties for an outbound binding type. There are fewer fields for the inbound type.

Fill in the general settings properties as described in General Settings.

Click Next.

The HL7 Version 2 Settings window appears.

Fill in the HL7 version 2 settings properties as described in HL7 Version 2 Settings.

Click Next.

The Communication Controls window appears.

Note –
The image above shows the properties for an outbound binding type. There are fewer properties for the inbound binding types.

Fill in the communication controls properties as described in Communication Controls.

Click Finish.

The WSDL file is created and appears inn the Projects window. The WSDL Editor appears, displaying the content of the file.

Abstract WSDL Properties

The Abstract WSDL Details page of the wizard specifies the request and response messages and the message type specified as the MSH.9 field value. The options on this page vary depending on the HL7 Binding type. The Response Message Type field only appears for two-way operations.

Property	Description
Operation Name	A name for the operation in the WSDL document.
Request Message	The HL7 XSD element or type used for the request message.
Request Message Type	The HL7 message type that the operation handles. This value should be the same as the message type entered in the MSH.9 field value.
Response Message Type	The HL7 XSD element or type used for the response message.

General Settings

The General Settings page of the HL7 Binding Wizard specifies the connection protocol and encoding details. The Outbound HL7 Bindings also include configuration properties for LLP message transport protocols.

The general settings are categorized into the following property types:

Endpoint properties

The Endpoint properties specify the connectivity information to the HL7 external system, and include the following configuration properties.

Property	Description
Transport Protocol Name:	The transport protocol used to transmit the HL7 message payload. For HL7 v2.X the only current transport protocol option is TCP/IP
Location	A URL used to connect to the HL7 external system.

Encoding Details

The Encoding Details specify the concrete properties associated with receiving or sending HL7 messages from or to the HL7 external system. The Encoding Details section include the following properties.

Property	Description
Use	The use type, which affects how a message is interpreted. The options are Literal or Encoded. The Encoded option specifies that the message is encoded using a well-defined encoding style.
Encoder	The encoding type associated with the message. This also defines the encoder type used to process the encoded data.

LLP Details

The LLP Details section defines the Lower Layer Protocol (LLP) used for the HL7 messages, and includes the following properties.

Property	Description
LLP Type:	The Lower Layer Protocol (LLP) type. Select one of the following types: MLLP v1.0 (Minimal Lower Layer Protocol) HLLP (Hybrid Lower Layer Protocol) MLLP v2.0 (Minimal Layer Protocol v2.0)
Start Block Character	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.
End Block Character	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.
End Data Character	The End Data Character value in decimal ASCII number from 1 to 127. To be strictly compliant , the value should be a carriage return, indicated by decimal 28.
HLLP Checksum	An indicator of whether the HLLP Checksum feature is enabled. This can only be enabled if the LLP Type is set to HLLP.
Persistence	An indicator of whether to store the HL7 message and ACKs into the persistence storage for recovery. Persistence can only be enabled for HLLP and MLLP v1.0; MLLP v2.0 has its own persistence.

MLLP Version 2 Properties (Outbound Only)

The MLLP Version 2 Properties are for outbound message only, and configure the Minimal Lower Layer Protocol (MLLP) version 2 property. This section includes the following properties.

Property	Description
No. of Retries on Receipt of NAK	The maximum configured number of attempts to send a message after receiving a negative acknowledgement.
Time Interval Between Retries	The duration in milliseconds to wait between each retry attempt.
Time Duration to Wait for ACK / NAK	The duration in milliseconds to wait for MLLP V2 commit positive or negative acknowledgement.

HL7 Version 2 Settings

The HL7 Version 2 Settings are divided into the following property types:

HL7 Version 2 Properties

The HL7 Version 2 Properties section includes the Acknowledgement Mode property.

Property	Description
Acknowledgement Mode	The type of acknowledgement used with HL7 transaction. Choose one of the following options: Original: An acknowledgement is sent from the receiving system's application layer once the application has successfully processed the message. This is also called the Application Acknowledgement. Enhanced: Both the Application Acknowledgement (Original Acknowledgement) and an Accept Acknowledgement are sent from the receiving system. The Accept Acknowledgement is sent once the message has been committed to safe storage and acknowledges that there is no need to resend the message.

Property

Description

Acknowledgement Mode

The type of acknowledgement used with HL7 transaction. Choose one of the following options:

Original: An acknowledgement is sent from the receiving system's application layer once the application has successfully processed the message. This is also called the Application Acknowledgement.
Enhanced: Both the Application Acknowledgement (Original Acknowledgement) and an Accept Acknowledgement are sent from the receiving system. The Accept Acknowledgement is sent once the message has been committed to safe storage and acknowledges that there is no need to resend the message.

MSH Properties

The MSH Properties section provides the HL7 MSH Header segment settings. It includes the following properties.

Property	Description
Validate MSH	An indicator of whether MSH segment validation is enabled.
Sequence No	An indicator of whether sequence number protocol is enabled.
Processing ID	The Processing ID value by which the MSH-11 segment in the received message is validated when validateMSH is enabled. MSH-11 is used to indicate whether a message is processed as defined in the HL7 Processing rules. The Processing ID options include the following: D - Debugging T- Training P- Production
Version ID	The HL7 Version ID value by which the MSH-12 segment in the received message is validated when validateMSH is enabled. The Version ID options are 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, and 2.6.
Sending Application	The sending application (MSH-03 segment) used to create the NAK for invalid HL7 messages. This is used to help identify this application from other participating applications within the network enterprise.
Sending Facility	The sending facility (MSH-04 segment) responsible for creating the NAK for invalid HL7 messages. This is used to help further identify participating facilities within the network enterprise.
Encoding Characters	The four encoding characters used to create the NAK for an invalid HL7 message. This attribute contains the four characters in the following order: Component separator Repetition separator Escape character Subcomponent separator The recommended value is ^~\& (that is, ASCII 94, 126, 92, and 38, respectively).
Field Separator	The separator between the segment ID and the first real field. This value defines the character that is used as a separator for the rest of the message. Enter the value as a decimal ASCII number ranging from 1 to 127. The default value is 124 which is the character "\|".

Message Properties

The Message Properties section contains the SFT configuration settings. HL7 versions 2.5, 2.5.1, and 2.6 add an SFT segment to every message. The binding not only sends and receives messages with the SFT segment, it can automatically create and populate the SFT configuration settings using information from the message properties for outbound mode, and from the ACK sent for inbound mode. This section includes the following properties.

Property	Description
SFT Enabled	An indicator of whether SFT segment processing is enabled.
Journaling	An indicator of whether journaling of the HL7 message and ACK is enabled.
Software Vendor Organization	The Software Vendor Organization field (SFT-1-Software Vendor Organization), which identifies the vendor who is responsible for maintaining the application. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.
Software Certified Version or Release Number	The Software Certified Version or Release Number, which is the value of the HL7 segment SFT-02. The current software version number or release number for the sending system, helps to provide a more complete profile of the application that is sending or receiving the HL7 messages. For example, if the sending system is Java CAPS 6.1, the value would be 6.1. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.
Software Product Name	The name of the software product that submitted the transaction, which is the value of the HL7 segment SFT-03. The software product name is a key component for identifying the sending application. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.
Software Product Information	The software product identification information, which is the value of the HL7 segment SFT-05. This may include a description of the software application, configuration settings, modifications made to the software, and so forth. This information is used for diagnostic purposes to help identify the application software. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.
Software Binary ID	The Software Binary ID, which is the value of HL7 segment SFT-04. This property is available starting with HL7 version 2.5. Software Binary IDs are issued by a vendor for each unique software version instance. These 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. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.
Software Install Date	The Software Install Date, which is the value of HL7 segment SFT-06. This is the date on which the submitting software was installed at the sending site. The install date can provide key information in regard to the behavior of an application. The date format is YYYYMMDDHHSS. This property only applies to HL7 versions 2.5, 2.5.1, and 2.6.

Communication Controls

The last page of the HL7 Binding Wizard, the Communication Controls page, provides configuration properties for the communication controls and recourse actions that control the sending and receiving of messages over a TCP/IP connection. These properties are defined by the Communication Control WSDL Extensibility Element, and help establish the Quality of Service (QoS) between the HL7 external system and HL7 endpoints.

The communication controls differ for inbound or outbound endpoints, therefore different pages are provided for inbound or outbound.

The recourse actions supported by the HL7 Binding Component can include the following values:

Reset: The binding component closes the connection with the HL7 external system and throws an alert.
Resend: The binding component resends the last sent message to the HL7 external system.
Suspend: The binding component closes the connection with the HL7 external system, suspends the endpoint from processing the messages, and throws an alert.
Skipmessage: The binding component remains connected but writes the message to an error queue.
Error: The binding component throws an Exception.

Each property in the table below allows you to enable or disable the control, select a value, and select a recourse action. If you do not enable the control, any setting you configure for that control are ignored.

Table 1 Inbound Communication Controls


Property	Description
MAX_NAK_SENT	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. Value: An integer indicating the appropriate maximum number. Recourse Actions: Suspend and Reset.
MAX_CANNED_NAK_SENT	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. Value: An integer indicating the appropriate maximum number. Recourse Actions: Suspend and Reset.

Table 2 Outbound Communication Controls


Property	Description
MAX_CONNECT_RETRIES	The maximum number of connection retires the binding component will attempt before executing the recourse action. Value: 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. Recourse Actions: Suspend and Error.
TIME_TO_WAIT_FOR_A_RESPONSE	The amount of time the binding component waits for a response from the external system before executing the configured recourse action. Value: An integer indicating the time interval in seconds. Recourse Actions: Resend, Reset, and Suspend.
MAX_NO_RESPONSE	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. Value: An integer indicating the maximum allowable number of “no-responses” from the external HL7 system. Recourse Actions: Suspend and Reset.
NAK_RECEIVED	The 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. Recourse Action: Resend, Reset, and Skipmessage.
MAX_NAK_RECEIVED	The maximum number of NAKs (negative acknowledgments) that the binding component accepts before it executes the configured recourse action. Value: An integer indicating the maximum number of NAKs allowed. Recourse Actions: Suspend, Reset, and Skipmessage.