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”. This tutorial assumes you know Java or any equivalent object-oriented language.
My previous tutorial "HL7 Programming using Java" gave you a foundational understanding of HL7 2.x message transmission, reception and message acknowledgement. Although this was fine for understanding the basics of HL7 message processing, this won't be sufficient for more complex message processing requirements we often encounter in the real world. You will often need a larger programming framework or a library that provides pre-built support to enable message construction, parsing, validation, transmission and reception of a broad set of HL7 2.x standards and its numerous trigger events/message types. One such framework or library that is available for the Java language is the HAPI HL7 Library. This library came out of work undertaken at a Canadian university in the early 2000s, and then grew steadily over the years to support nearly all HL7 Version 2.x Standards (includes 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, and 2.6 at the time of writing this article). The library has been used both directly and "under the covers" by numerous commercial as well as open source health interface applications. I have used this software both directly in some custom applications that I wrote in Java as well as indirectly when I used some popular healthcare interface engines such as Mirth Connect in the past. The library is also being used to power some of the latest FHIR-based applications and initiatives whose primary goal being to make the task of interoperability between web-enabled healthcare applications even easier. In this introductory tutorial, my task is to introduce you to the very basics of the HAPI toolkit/library by creating a basic patient admit HL7 message using the HL7 2.3 standard.
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 (optional) here
- You can also find all the code demonstrated in the tutorial on GitHub here
“Courageous people do not fear forgiving, for the sake of peace.” ~ Nelson Mandela
Quick Introduction to ADT Messages
HL7 ADT messages are one of the most popular message types used in HL7-enabled systems and are used communicate core patient information captured in the EMR (Electronic Medical Record) to other ancillary/supporting systems such as lab, radiology, etc. This message is often transmitted when the patient information is either captured initially or when it changes because of events such as admission, transfer or discharge in a clinical setting. There are many types of ADT messages including ADT A01 (used during admit), A02 (used during transfer), A03 (used during end of visit or discharge), etc. There are also other HL7 message types that pertain to orders, results, clinical reports, scheduling and billing. The HAPI library provides built-in support to create all these message types. In this particular tutorial, I will use the HAPI library to create a ADT A01 message. This message type or trigger event that we will create will include the following message segments that are mandatory:
- MSH segment: Every HL7 message will carry this segment if you recall from my earlier tutorial. This segment will carry information such as the sender and receiver of the message, the type of message, and the date and time information of this message
- EVN segment: This segment will include information pertaining to the event that occurred (in our case this is due to an admission of a fictional patient)
- PID segment: This segment carries information pertaining to patient demographics such as such as name of the patient, patient identifier and address, etc
- PV1 segment: This segment typically contains information about the patient’s stay, where they are assigned and also the referring doctor
Message construction gets pretty ugly if we don't separate the various steps involved into smaller methods. The approach I show below is a suggestion only. Please feel free to create your own factory methods, builder classes and any other utility classes needed especially if you are wanting to support multiple message types in your application.
There are many variations of the factory method pattern, and most of them tend to implement a static method which is responsible for constructing an object and returning this created object. It is the static method that tends to abstract the construction process of an object. You typically define an interface for creating an object in the superclass and you then let the subclasses decide which classes to instantiate depending on the parameters passed. However, you can also delegate the construction to another class entirely. So, lots of options and approaches are available to you. Ultimately, the factory method lets the main class (or the "client") defer any instantiation to other classes based on the parameters passed. Here, I am simply using a builder class inside the factory method.
In the code shown below and as described earlier the delegation of the actual construction of our ADT A01 message is left to a ADT message builder class called "OurAdtA01MessageBuilder" here for the lack of better imagination on my part. This builder class shown below helps construct the various parts of the ADT A01 message step by step. Using the builder pattern will be extremely useful even when using a HL7 library like HAPI since there is just way too many optional segments and components that you will deal with when dealing with the HL7 2.x standard. The other advantage of this approach is that you can pass in data into the constructor of the builder class to build the ADT message with the required data values from your HL7 application (not shown here). This a style I prefer. However, feel free to choose any style that suits you or your organization. This is after all a tutorial on using HAPI and not on software design. :-)
The results of running the above program is shown above. Running the program produces a HL7 message that is ready for transmission to a remote HL7 system. You can also inspect the two output files generated by the program to get an idea of what a pipe delimited HL7 file and XML formatted file looks like. Please note that the pipe delimited output file has special unprintable characters within it that help in the "message enveloping" that is required. You can inspect this file using any Hex editor if you are curious to see where these characters are in the file.
That concludes this little tutorial to create our first ADT HL7 message and its various constituent parts using the HAPI library. That was pretty easy, hey? Unlike some other HL7 tools in the market, HAPI provides strongly typed classes to generate various HL7 messages including predefined as well as custom message segments very quickly. The various classes and their methods and other utility functions provided by the library help remove any tedium and guess work when assembling, transmitting, receiving, parsing and validating HL7 messages that we often need to tackle when developing a message processing application. We also used a powerful class called HapiContext in this tutorial that helped encode the java message object and makes it ready for message serialization required for message transmission (or message storage). This class forms the foundation of most of the message processing functionality that is provided by the HAPI library We will encounter this class again when reviewing other features provided by the HAPI library in our subsequent tutorials. See you then!