HL7

HL7 Component

The hl7 component is used for working with the HL7 MLLP protocol and the HL7 model using the HAPI library.

This component supports the following:

• HL7 MLLP codec for Mina
• HL7 DataFormat
• Even more easy-of-use as its integrated well with the camel-mina component.

HL7 MLLP protocol

HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose a HL7 listener that accepts HL7 requests over the TCP transport.

To expose a HL7 listener service we reuse the existing camel-mina component where we just use the HL7MLLPCodec as codec.

The HL7 MLLP codec has the following options:

Exposing a HL7 listener

In our spring xml file we configure an endpoint to listen for HL7 requests using TCP:

        <endpoint id="hl7listener" uri="mina:tcp://localhost:8888?sync=true&amp;codec=hl7codec"/>

Notice we configure it to use camel-mina with TCP on the localhost on port 8888. We use the sync=true to indicate that this listener is synchronous and therefore will return a HL7 response to the caller. Then we setup mina to use our HL7 codec with codec=hl7codec. Notice that hl7codec is just a spring bean id, so we could have named it mygreatcodecforhl7 or whatever. The codec is also setup in the spring xml file:

    <bean id="hl7codec" class="org.apache.camel.component.hl7.HL7MLLPCodec">
        <property name="charset" value="iso-8859-1"/>
    </bean>

And here we configure the charset encoding to use, and iso-8859-1 is commonly used.

The endpoint hl7listener can then be used in a route as a consumer, as this java DSL example illustrates:

    from("hl7socket").to("patientLookupService");

This is a very simple route that will listen for HL7 and route it to a service named patientLookupService that is also a spring bean id we have configured in the spring xml as:

    <bean id="patientLookupService" class="com.mycompany.healtcare.service.PatientLookupService"/>

And another powerful feature of Camel is that we can have our busines logic in POJO classes that is not at all tied to Camel as shown here:

public class PatientLookupService {
    public Message lookupPatient(Message input) throws HL7Exception {
        QRD qrd = (QRD)input.get("QRD");
        String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();

        // find patient data based on the patient id and create a HL7 model object with the response
        Message response = ... create and set response data
        return response
    }

Notice that this class is just using imports from the HAPI library and none from Camel.

HL7 Model

The HL7 model is Java objects from the HAPI library. Using this library we can encode and decode from the EDI format (ER7) that is mostly used with HL7.
With this model you can code with Java objects instead of the EDI based HL7 format that can be hard for humans to read and understand.

The ER7 sample below is a request to lookup a patient with the patient id 0101701234.

MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4
QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||

Using the HL7 model we can work with the data as a ca.uhn.hl7v2.model.Message.Message object.
To retrieve the patient id for the patient in the ER7 above you can do this in java code:

Message msg = exchange.getIn().getBody(Message.class);
QRD qrd = (QRD)msg.get("QRD");
String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();

Camel has build in type converters so when this operation is invoked:

Message msg = exchange.getIn().getBody(Message.class);

Camel will converter the received HL7 data from String to the Message object. This is powerful when combined with the HL7 listener, then you as the end-user don't have to work with byte[], String or any other simple object formats. You can just use the HAPI HL7 model objects.

  DataFormat hl7 = new HL7DataFormat();
  ...
  from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");

  DataFormat hl7 = new HL7DataFormat();
  ...
  from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");

  from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out");
  from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");

Samples

In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain String types in this example:

In the next sample we want to route HL7 requests from our HL7 listener to our business logic. We have our business logic in a plain POJO that we have registered in the registry as hl7service = for instance using Spring and letting the bean id = hl7service.

Our business logic is a plain POJO only using the HAPI library so we have these operations defined:

Then we setup the Camel routes using the RouteBuilder as:

Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigued on the Camel Message. This let us much more easily define our routes using the fluent builders.
If we do not use the HL7 DataFormat then we do not gains these headers and we must resort to a different technique for computing the MSH trigger event (= what kind of HL7 message it is). This is a big advantage of the HL7 DataFormat over the plain HL7 type converters.