This is part of my HL7 article series. Before we get started on this tutorial, have a quick look at my earlier article titled “A Very Short Introduction to the HL7 2.x Standard”. One of my earlier tutorials in this series titled "HL7 Programming using Java" gave you a foundational understanding of HL7 2.x message transmission, reception and message acknowledgement. I then introduced you to a Java library called "HAPI" and showed you an example of how a HL7 message can be easily created using the library in my tutorial titled "HL7 Programming using HAPI - Creating HL7 Messages". In this tutorial, we will build on the previous tutorial and look at how we can transmit a HL7 message once we have assembled one to a remote system using the HAPI library.
Tools for Tutorial
- JDK 1.4 SDK or higher
- Eclipse or any other Java IDE (or even a text editor)
- Download HAPI compiled library from the HAPI project website
- View HAPI source code on their GitHub site here
- Download HAPI Test Panel from here
- You can also find all the code demonstrated in the tutorial on GitHub here
“Every human is an artist. The dream of your life is to make beautiful art.” ~ Don Miguel Ruiz
Most HL7 systems communicate messages with one another using the Minimum Lower Layer Protocol (often shortened to “MLLP”). MLLP can be simply considered a wrapper protocol on top of the TCP/IP protocol since the communicating systems need to be able to recognize the start and the end of each message (i.e. headers and trailers) as TCP/IP data is simply a stream of continuous bytes. MLLP typically uses non-printable characters to serve as wrapping characters around the core HL7 message information exchanged between these systems. If one were programming a HL7 system from scratch, then you will need to be familiar with many aspects of network programming such as sockets to accomplish the task of coordinating the steps require to establish TCP/IP communications between the two systems involved. Luckily, HAPI abstracts that for you and provides with some helpful classes to enable message exchange. The following are some of the features provided for HL7 message communication by HAPI:
- Transmit HL7 messages over MLLP protocol
- Transmit HL7 messages through a serialized file, email, etc
- Transmit HL7 messages through HTTP (and HTTPS) using the HoH specification (stands for "HL7 over HTTP")
- Transmit HL7 messages over a Restful Web Service Interface (using the HAPI HL7 FHIR Tooling)
Message Transmission - Overview and HAPI HL7 Test Panel Setup
In the previous tutorial, we saw the we could easily encode a HL7 message for serialization to print to the program console. The job of serialization was handled by a special class called Pipe Parser which is one of the many types of parser classes that HAPI supports. This parser enables the use of pipe delimiter characters during the message encoding and decoding process. Another type of parser that is available in the library is the XML Parser which helps encode and decode the HL7 message in XML format. HAPI provides many such useful classes to enable the programmer to handle the message processing in multiple ways. In this tutorial, we will construct a message and transmit the HL7 message to a HL7 listener running on our own machine. Rather than building something from scratch we will use an extremely helpful testing tool provided by the authors to test HL7 connectivity.
Setting up the HAPI Test Panel is very easy. Simply download the TestPanel compiled Jar file or the compilable source code. Please ensure that you have a suitable Java runtime installed on your machine (should be included in your JDK if you downloaded it previously). Then launch the test panel executable jar file. Since we are transmitting the HL7 message, we need to set up a listener. Create a new HL7 MLLP listener by adding a new one using the bottom left panel as shown in the screen capture below, choose the default port number the test panel suggest or enter a port number that does not conflict with any existing applications and hit the "Start" button. If the listener turns green in color, then you have successfully enabled a HL7 listener on your computer. See screen capture below that shows the HAPI Test Panel running on my computer.
By running the code shown above, you should be able to send a HL7 ADT message to the listener and receive a message acknowledgement back. Message acknowledgement is a complex topic in itself and I will cover that in more detail in a separate tutorial on building HL7 listeners using the HAPI library. For now, just note that the HAPI Test Panel provides a nice breakdown of the message exchange activity showing the received message as well as the acknowledgment message that was transmitted back to our Java client. You can select the received or sent message in the Test Panel and "Edit" it to see a nice tree structure breakdown of the various constituents of these messages if you wanted to verify whether the information was transmitted correctly. A screen capture of this functionality is shown below.
Sending Multiple Messages
In many health information systems, the HL7 messages are often created and then serialized to a file for transmission later. This serialized file is then FTP'ed or transmitted over a file sharing network to a separate system capable of communicating using sockets with the remote party. There are two variations involved with this approach one of which is Batching which enables you to send multiple messages in a single file using a special envelope consisting of special file and batch headers. Batching is a complex topic in itself and I will cover that in a separate tutorial. However, the scenario I am referring to here is how to handle reading and sequential transmission of a series of HL7 messages contained in a file. Please see an example of how you can handle such a scenario below. I have also included the test file in my GitHub page here. Running the code below should enable to transmit the messages to the HAPI Test Panel if you have it configured using the instructions that were provided earlier. Screenshot of the HAPI Test Panel showing the transmitted messages that were received by the listener is shown below the source code listed here.
“We may encounter many defeats but we must not be defeated.” ~ Maya Angelou
This concludes a quick overview and tutorial on using HAPI HL7 library for message transmission using the MLLP over TCP/IP. There are a lot of additional classes in the HAPI library that enable you to control the behavior of the MLLP and socket connectivity over and beyond what was shown in this tutorial. You can for instance send a message to the server through one port and configure the client to receive the message response through a different port. I will let you explore these features on your own. However, we will cover other features including message reception, parsing and validating in subsequent tutorials. See you then!