Sunday, March 12, 2017

Receiving HL7 Messages with WSO2 EI

Before getting EI involved in this story,let's get to know what are these HL7 messages? Why do we need such messages ? From where does these messages come?

What is HL7 ?

HL7 refers to a set of international standards defined for exchanging, integrating, sharing, and retrieval of clinical and administrative data between software applications used by various healthcare providers. In simple words HL7 is the common language that is used by different types of health care instruments to talk to each other.

Use case

Now let's see how these HL7 messages can be received from WSO2 EI using a simple use case.

In order to simulate emitting messages from Health instruments, we will be using Hapi Test Panel. If you are not familiar with the Hapi Test Panel you can go thorough this previous blog post about Hapi Test Panel.

Messages sent from the Hapi Test Panel will be captured by WSO2 EI's HL7 inbound endpoint and the mediated messages will be saved in a MYSQL database as shown in the below architecture diagram.


Note that we are building the above use case starting from the right side of the above diagram.

   1.  Create MySQL table and data service for storing messages
   2.  Writing Mediation logic for extracting data from HL7 messages and calling data service
   3.  Writing HL7 inbound to receive HL7 messages
   3.  Sending HL7 messages to WSO2 EI from Hapi Test Panel

    Note : As the purpose of this blog post is to demonstrate the HL7 capabilities of EI and not to deploy in any production     environment as is, we will be creating synapse configurations using management console of EI.

Creating data service in WSO2 EI

Let's first create the MySQL table for storing mediated messages. Below given is the sample table that we created in MySQL database.

   1.  Copy the MySQL driver in to EI_HOME/lib folder and start EI by running script at EI_HOME/bin
   2.  Log into the EI management console and Go to Configure --> Datasources and click Add Datasource
   3.  Fill in the details as per your created table in MySQL and Save

   4.  Then go to Main --> Generate under Data Source
   5.  Go through the wizard and generate the data service.

Note the data service name that we have used in this use case is "patient_data_DataService"

   6.  Go to Main --> Endpoints and click on Add endpoint
   7.  Choose Address Endpoint from the list of endpoints and fill in the data as given below

Since our data service name is "patient_data_DataService", our endpoint address is "http://localhost:8280/services/patient_data_DataService"

Writing mediation for the HL7 messages in WSO2 EI

   1.  Select Main --> Sequences and click on Add Sequence
   2.  Switch to the source view and paste the below given sequence

Note that we have used a payload factory mediator to extract data from HL7 message and at the end of the sequence we are calling the data service with the newly built payload.

Creating HL7 Inbound endpoint in WSO2 EI

   1.  Go to Main --> Inbound Endpoints
   2.  Then click on Add Inbound Endpoint
   3.  Give an endpoint name and select Type as HL7
   4.  Fill in the details as shown in the below image

Note that the inbound HL7 port is 20000

Sending HL7 messages from Hapi Test Panel

Send below HL7 message of type ORU^R01 and version 2.4

Now go to your MySQL table and verify whether the following entry is inserted.

Note that the payload factory mediator is written only to accept messages of type ORU^R01 and version 2.4 and in a real use case we can write the mediation logic in a more generic way to accept differnt type of HL7 messages.

Sending HL7 messages using Hapi Test Panel

The purpose of this blog post is to describe how to install the Hapi Test Panel in an ubuntu environment and send HL7 messages using that.

What is Hapi Test Panel ?

The HAPI Test Panel is a tool that can be used to send, receive and edit HL7 messages.

How to install in Ubuntu ?

There are multiple ways to install Hapi Test panel and you can find more information here. The approach that I followed was
   1.  Download hapi-testpanel-2.0.1-linux.tar.bz2 from download page
   2.  Extract the download to your preferred location
   3.  Run the file which is at the Home of the Hapi Test Panel extraction

How to send HL7 messages using Test Panel ?

   1.  Click on Test Menu and then select Populate Test Panel with Sample Message and Connections
   2.  You can send the created new message by clicking Send button which is in the top of the middle panel

If you need any specific version or type of message, you can click on File Menu and then select New Message. You can choose your preferred message version and type from the pop up window.

Enjoy sending HL7 messages with Hapi Test Panel !!!