The HL7 transport allows you to handle Health Level 7 International (HL7) messages. The following sections describe how to install, enable, and configure the HL7 transport:

WSO2 ESB uses the HAPI parser to provide HL7 support, which currently does not support HL7v3.

Installing the HL7 feature

The HL7 transport is available as a feature in WSO2 Enterprise Service Bus (WSO2 ESB). For instructions on installing the HL7 feature, see Installing the Axis2 transport HL7 feature.

Enabling the transport

You configure the HL7 transport in the <ESB_HOME>/repository/conf/axis2/axis2.xml file as follows:

<transportReceiver name="hl7" class="org.wso2.carbon.business.messaging.hl7.transport.HL7TransportListener">
    <parameter name="port">9292</parameter>
</transportReceiver>
<transportSender name="hl7" class="org.wso2.carbon.business.messaging.hl7.transport.HL7TransportSender">
    <!--parameter name="non-blocking">true</parameter-->
</transportSender>
...
<messageFormatters>
  <messageFormatter contentType="application/edi-hl7" class="org.wso2.carbon.business.messaging.hl7.message.HL7MessageFormatter"/>
...
</messageFormatters>
...
<messageBuilders>
  <messageBuilder contentType="application/edi-hl7" class="org.wso2.carbon.business.messaging.hl7.message.HL7MessageBuilder"/>
</messageBuilders>

Creating an HL7 proxy service

For information on creating a proxy service that uses the HL7 transport, see Creating an HL7 Proxy Service.

Configuring the transport

You can optionally configure the following behavior of the HL7 transport.

Conformance profile

Add the parameter "transport.hl7.ConformanceProfilePath" in the proxy service to point to a URL where the HL7 conformance profile (XML file) can be found.

Message pre-processing

Add the parameter "transport.hl7.MessagePreprocessorClass" to point to an implementation class of the interface "org.wso2.carbon.business.messaging.hl7.common.HL7MessagePreprocessor", which is used to process raw HL7 messages before parsing them so that potential errors in the messages can be rectified using the transport.

Acknowledgement and validation

You can enable or disable automatic message acknowledgement and validation. When automatic message acknowledgement is enabled, an ACK is immediately sent back to the client after receiving a message. When it is disabled, the user is given control to send back an ACK/NACK message from an ESB sequence after any message validations or related tasks. Different types of message validations done at the message builder are removed for behavioral consistency of the message builder with the transport.

When using a transport such as HTTP, to create an ACK/NACK message from an HL7 message in the flow, specify an axis2 scope message context property "HL7_GENERATE_ACK" and set its value to true. This ensures that an ACK/NACK message is created automatically when a message is sent (using the HL7 formatter). By default, an ACK message is created. If a NACK message is required instead, use the message context properties "HL7_RESULT_MODE" and "HL7_NACK_MESSAGE" as described below.

In the proxy service, add the following parameters to enable or disable auto-acknowledgement and validation:

<proxy>...
   <parameter name="transport.hl7.AutoAck">true|false</parameter> <!-- default is true -->
   <parameter name="transport.hl7.ValidateMessage">true|false</parameter> <!-- default is true -->
</proxy>

When ‘AutoAck’ is false, you can set the following properties inside an ESB sequence.

<property name="HL7_RESULT_MODE" value="ACK|NACK" scope="axis2" /> <!-- notice the properties should be in axis2 scope -->

When the result mode is ‘NACK’, you can use the following property to provide a custom description of the error message.

<property name="HL7_NACK_MESSAGE" value="<ERROR MESSAGE>" scope="axis2" />

You can use the property "HL7_RAW_MESSAGE" in the axis2 scope to retrieve the original raw EDI format HL7 message in an ESB sequence. The user doesn't have to convert from XML to EDI again, so this usage may be particularly helpful inside a custom mediator.

To control the encoding type of incoming messages, set the Java system property "ca.uhn.hl7v2.llp.charset".

Configuring application acknowledgement

In general, we don't wait for the back-end application's response before sending an "accept-acknowledgement" message to the client. If you do want to wait for the application's response before sending the message, define the following property in the InSequence:
<property name="HL7_APPLICATION_ACK" value="true" scope="axis2"/>

In this case, the request thread will wait until the back-end application returns the response before sending the "accept-acknowledgement" message to the client. You can configure how long request threads wait for the application's response by configuring the time-out in milliseconds at the transport level:

<transportReceiver name="hl7" class="org.wso2.carbon.business.messaging.hl7.transport.HL7TransportListener"> <parameter name="transport.hl7.TimeOut">1000</parameter> </transportReceiver>

For more information on configuring the proxy service for application acknowledgement, see Application acknowledgement in Creating an HL7 Proxy Service.

Browser not supported