HL7 Test Server using JBoss Fuse + Apache Camel

4 min readMar 15, 2016

When constructing a HL7 application, it is important to have a HL7 test server to test the sending and receiving of HL7 messages. And while there are a number of HL7 Test Applications available that allow you to create, edit, send, and receive HL7 Messages such as HAPI Test Panel and 7Edit, it can be necessary to have a test server that offers the benefits of customizing HL7 messages or behaviors that test edge cases in your application.

JBoss Fuse Platform

The JBoss Fuse platform provides a modular integration platform that is perfect for creating this extensible test server. With Apache Camel providing a HL7 Component which offers a HL7 MLLP codec for Mina and Netty4, as well as a Data Format using the HAPI library, the work to setup a TCP server and transforming messages is greatly reduced. In addition, OSGi services provide POJO business functions while being decoupled from routing logic.

Architecture

The following is an Architecture Diagram of the test server.

The Gateway HL7 Server receives HL7 requests, interacts with a Health Service to perform business functions, and then returns a HL7 response back to the caller. In addition, the Gateway HL7 Server can read HL7 messages on the file system and send to a HL7 Application. Responses from the HL7 Application can be verified.

Of special note, this application is a working example of the code samples at the bottom of the Camel HL7 documentation.

HL7 Listener

The following is a Camel Route to listen for HL7 messages

The route listens for HL7 messages using the Netty4 Camel Component and the HL7 codec. The message is unmarshaled from a String to a HAPI object. A content based router then routes the payload to the appropriate handler. At this time only a A19 message is supported, but new handler can be added at any time. The A19 handler interacts with a Health Service and a HAPI response object is constructed. This HAPI object is marshaled to a String and returned back to the caller.

Implementation

The implementation for this server can be found on my github account at the following location: https://github.com/joelicious/hl7-test-server

Let’s take a look at the individual modules:

features.hl7 : A maven module that contains a Karaf Feature file to make deployments easier. The four features are

service-health : deployment of only the Health Service
service-health-client : an example client of the Health Service. It also is a basic test of the service.
gateway-hl7 : deployment of the HL7 Test Server.
gateway-hl7-client : an example client of the HL7 Test Server. It also is a basic test of the server.

gateway.hl7.client : A maven module that uses Blueprint to construct a Camel Context with a route to read HL7 payloads from the filesystem and send to the gateway-hl7. Of note, this client can be replaced with HAPI test panel.
gateway.hl7.server : A maven module that uses Blueprint to construct a Camel Context with routes to synchronously send and receive HL7 payloads.
service.health : A maven module that contains the Health Service Interface. Other modules depend only on this interface, and not the implementation. In addition there are no framework dependencies, allowing for highest amount of re-usability for this business function.
service.health.impl : A maven module that implements the service.health interface.
service.health.client : A maven module that interacts with the Health Service to test its function.

Installation

The code currently is dependent on JBoss Fuse 6.2.0.redhat-133. Please follow the github documentation for further updates, but in general, the deployment instructions are:

features:addurl mvn:org.jboss.fuse/hl7.features/0.0.1-SNAPSHOT/xml/features
features:install gateway-hl7

To install the individual test clients, perform the following:

features:install gateway-hl7-client
features:install service-health-client

The gateway-hl7-client expects that a HL7 payload is placed on the filesystem at the following location:

${JBOSS_FUSE_HOME}/test-data/rawhl7

and an example payload is located at https://github.com/joelicious/hl7-test-server/blob/master/gateway.hl7.client/src/test/resources/test-data/QRY_A19.hl7

In addition, HAPI test panel can be used to send messages to the HL7 test server for simple verifications.

Summary

An extensible HL7 test server framework has been outlined. This test server can be used to test your HL7 application by providing a customizable platform for HL7 request/response interactions. Since the routing logic depends on a POJO Health Service Interface, there is nothing to stop you from making the business logic in Health Service as simple or complicated as you need for testing. At this time only a programmatic response is performed, but you could extend this project to store test patient information in a database for certain test cases. Also, the routing can be customized to vary the amount of time to respond to a request or even occasionally not respond at all. The goal being, test as many edge cases as you can!