Page Comparison

The HL7 Transport transport allows you to handle Health Level 7 International (HL7) messages. It is available when you install the Axis2 Transport HL7 feature.The following sections describe how to install, enable, and configure the HL7 transport: 

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 enable the HL7 transport in in the <ESB_HOME>/repository/conf/axis2/axis2.xml file as follows:

<transportConfig>
    <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>
</transportConfig>
...
<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 see Creating an HL7 Proxy Service.

Configuring the transport

...

Add the parameter "transport.hl7.MessagePreprocessorClass" in the proxy service 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

...

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.

...

Code Block
language html/xml
<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.

...

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

Validating messages

By default, the HL7 transport validates messages before building their XML representation. You configure validation with the following parameter in the proxy service:

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

When transport.hl7.ValidateMessage is set to false, you can set the following parameters to handle invalid messages:

• transport.hl7.BuildInvalidMessages: when set to true, builds a SOAP envelope with the contents of the raw HL7 message inside the <rawMessage> element.
• transport.hl7.PassThroughInvalidMessages: when BuildInvalidMessages is set to true, you use this parameter to specify whether to pass this message through (true) or to throw a fault (false).

The following diagram illustrates these flows.

Image Added

Configuring the thread pool

The HL7 transport uses a thread pool to manage connections. A larger thread pool provides greater performance, because the transport can process more messages simultaneously, but it also uses more memory. You can add the following properties to the proxy service to configure the thread pool to suit your environment:

• transport.hl7.corePoolSize: the core number of threads in the pool. Default is 100.
• transport.hl7.maxPoolSize: the maximum number of threads that can be in the pool. Default is 200.
• transport.hl7.idleThreadKeepAlive: the time in milliseconds to keep idle threads alive before releasing them. Default is 10000 (10 seconds). 

Storing messages

You can use the HL7 message store to automatically store HL7 messages, allowing you to audit and replay messages as needed. The HL7 store is a custom message store implementation on top of Open JPA. To use the message store, you take the following steps:

1. Create an empty database in your RDBMS, and then create a message store configuration that points to that database.
2. Create a sequence that points to that message store configuration.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">

   <proxy name="HL7Store" startOnLoad="true" trace="disable" transports=”hl7”>
      <description/>
      <target>
         <inSequence>
            <property name="HL7_RESULT_MODE" value="ACK" scope="axis2"/>
            <log level="full"/>
            <property name="messageType" value="application/edi-hl7" scope="axis2"/>
            <clone>
               <target sequence="StoreSequence"/>
               <target sequence="SendSequence"/>
            </clone>
         </inSequence>
      </target>
      <parameter name="transport.hl7.AutoAck">false</parameter>
      <parameter name="transport.hl7.Port">55557</parameter>
      <parameter name="transport.hl7.ValidateMessage">false</parameter>
   </proxy>

   <sequence name="StoreSequence">
      <property name="OUT_ONLY" value="true"/>
      <store messageStore="HL7StoreJPA"/>
   </sequence>

   <sequence name="SendSequence">
      <in>
         <send>
            <endpoint>
               <address uri="hl7://localhost:9988"/>
            </endpoint>
         </send>
      </in>
      <out>
         <log level="full"/>
         <drop/>
      </out>
   </sequence>

   <messageStore class="org.wso2.carbon.business.messaging.hl7.store.jpa.JPAStore"
                 name="HL7StoreJPA">
      <parameter name="openjpa.ConnectionDriverName">org.apache.commons.dbcp.BasicDataSource</parameter>
      <parameter name="openjpa.ConnectionProperties">DriverClassName=com.mysql.jdbc.Driver, Url=jdbc:mysql://localhost/hl7storejpa,  MaxActive=100,  MaxWait=10000,  TestOnBorrow=true,  Username=root,  Password=root</parameter>
      <parameter name="openjpa.jdbc.DBDictionary">blobTypeName=LONGBLOB</parameter>
   </messageStore>

</definitions>

In this configuration, when the HL7 proxy service runs, an HL7 service will start listening on the port defined in the transport.hl7.Port service parameter. When an HL7 message arrives, the proxy will send an ACK back to the client as specified in the HL7_RESULT_MODE property. The Clone mediator is used inside the proxy to replicate the message into the Send and Store sequences, where the message is sent to the specified endpoint and is also stored in the message store HL7StoreJPA.

The HL7StoreJPA message store is a custom message store implemented in org.wso2.carbon.business.messaging.hl7.store.jpa.JPAStore. It takes OpenJPA properties as parameters. In this example, the openjpa.ConnectionProperties and openjpa.ConnectionDriverName properties are used to create an Apache DBCP pooled connection set to a MySQL database. You will need to create the database specified in the connection properties and provide the database authentication details matching your database. You may also need to place the JDBC drivers for your database into <ESB_HOME>/repository/components/lib. 

You can view the messages in this message store using the HL7 Console UI. You can search for messages on the unique message UUID or HL7 specific Control ID. The search field supports the wildcard ‘%’ to allow LIKE queries. The table can also be filtered to search for content within messages.

Selected messages can be edited and injected into a proxy service. Reinjecting a message to the same service will result in a new message being stored with a different message UUID.