Camel Component: Hl7 - 6.3

Talend ESB Mediation Developer Guide

EnrichVersion
6.3
EnrichProdName
Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
task
Design and Development
EnrichPlatform
Talend ESB

The hl7 component is used for working with the HL7 MLLP protocol and HL7 v2 messages using the HAPI library. This component supports the following:

  • HL7 MLLP codec for Mina

  • Agnostic data format using either plain String objects or HAPI HL7 model objects.

  • Type Converter from/to HAPI and String

  • HL7 DataFormat using HAPI library

  • Even more ease-of-use as it's integrated well with the Camel-Mina and Camel-Mina2 (for Camel 2.11+) components.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-hl7</artifactId>
   <!-- use the same version as your Camel core version -->
   <version>x.x.x</version>
</dependency>

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 or Mina2 components where we just use HL7MLLPCodec as codec.

The HL7 MLLP codec has the following options:

Name

Default Value

Description

startByte0x0bThe start byte spanning the HL7 payload.
endByte10x1cThe first end byte spanning the HL7 payload.
endByte20x0dThe 2nd end byte spanning the HL7 payload.
charsetJVM DefaultThe charset name encoding to use for the codec. If not provided, Camel will use the JVM default Charset.
convertLFtoCRtrue (Camel 2.11: false )Will convert \n to \r (0x0d, 13 decimal) as HL7 usually uses \r as segment terminators. The HAPI library requires the use of \r. Default value of true pre-Camel 2.11, false starting with Camel 2.11.
validatetrueWhether HAPI Parser should validate or not.
parserca.uhn. hl7v2. parser. PipeParserStarting with Camel 2.11, to use a custom parser. Must be of type ca.uhn.hl7v2.parser.Parser.

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&codec=#hl7codec"/>
   <!-- for Camel 2.11: use uri="mina2:tcp..." -->   

Notice that we use TCP on localhost on port 8888. We use 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 set up 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("hl7listener").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"/>

Another powerful feature of Camel is that we can have our business logic in POJO classes that is not tied to Camel as shown here:

import ca.uhn.hl7v2.HL7Exception; 
import ca.uhn.hl7v2.model.Message; 
import ca.uhn.hl7v2.model.v24.segment.QRD;
            
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 uses imports from the HAPI library and not from Camel.

HL7 Model using java.lang.String

The HL7MLLP codec uses plain Strings as its data format. Camel uses its Type Converter to convert to/from strings to the HAPI HL7 model objects. However, you can use plain String objects if you prefer, for instance if you wish to parse the data yourself.

HL7 Model using HAPI

The HL7v2 model uses Java objects from the HAPI library. Using this library, we can encode and decode from the EDI format (ER7) that is mostly used with HL7v2. 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 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 object. To retrieve the patient ID in the message 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 built-in type converters, so when this operation is invoked:

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

If you know the message type in advance, you can be more type-safe:

QRY_A19 msg = exchange.getIn().getBody(QRY_A19.class); 
String patientId = msg.getQRD().getWhoSubjectFilter(0).getIDNumber().getValue(); 

Camel will convert the received HL7 data from String to Message. 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 HL7v2 model objects.

Message Headers

The unmarshal operation adds these MSH fields as headers on the Camel message:

Key

MSH field

Example

CamelHL7SendingApplicationMSH-3MYSERVER
CamelHL7SendingFacilityMSH-4MYSERVERAPP
CamelHL7ReceivingApplicationMSH-5MYCLIENT
CamelHL7ReceivingFacilityMSH-6MYCLIENTAPP
CamelHL7TimestampMSH-720071231235900
CamelHL7SecurityMSH-8null
CamelHL7MessageTypeMSH-9-1ADT
CamelHL7TriggerEventMSH-9-2A01
CamelHL7MessageControlMSH-101234
CamelHL7ProcessingIdMSH-11P
CamelHL7VersionIdMSH-122.4

Options

The HL7 Data Format supports the following options:

Option

Default

Description

validatetrueWhether the HAPI Parser should validate using the default validation rules. Camel 2.11: better use the {{parser}} option and initialize the parser with the desired HAPI {{ValidationContext}}
parserca.uhn. hl7v2. parser. GenericParserStarting with Camel 2.11, to use a custom parser. Must be of type ca.uhn.hl7v2.parser.Parser. Note that GenericParser also allows for parsing XML-encoded HL7v2 messages.

Dependencies

To use HL7 in your Camel routes you'll need to add a Maven dependency on camel-hl7 listed above, which implements this data format. The HAPI library is split into a base library and several structures libraries, one for each HL7v2 message version.

By default camel-hl7 only references the HAPI base library. Applications are responsible for including structures libraries themselves. For example, if a application works with HL7v2 message versions 2.4 and 2.5 then the following dependencies must be added:

<dependency>
    <groupId>ca.uhn.hapi</groupId>
    <artifactId>hapi-structures-v24</artifactId>
    <!-- use the same version as your hapi-base version -->
    <version>1.2</version>
</dependency>
<dependency>
    <groupId>ca.uhn.hapi</groupId>
    <artifactId>hapi-structures-v25</artifactId>
    <!-- use the same version as your hapi-base version -->
    <version>1.2</version>
</dependency>

Alternatively, an OSGi bundle containing the base library, all structure libraries and required dependencies (on the bundle classpath) can be downloaded from the central Maven repository:

<dependency>
    <groupId>ca.uhn.hapi</groupId>
    <artifactId>hapi-osgi-base</artifactId>
    <version>1.2</version>
</dependency>

Note that the version number must match the version of the hapi-base library that is transitively referenced by this component.

See the Camel Website for examples of this component in use.

Terser language (Camel 2.11)

HAPI provides a Terser class that provides access to fields using a commonly used terse location specification syntax. The Terser language allows to use this syntax to extract values from messages and to use them as expressions and predicates for filtering, content-based routing etc.

Sample:

import static org.apache.camel.component.hl7.HL7.terser;
...
 
   // extract patient ID from field QRD-8 in the QRY_A19 message above and put into message header
   from("direct:test1")
      .setHeader("PATIENT_ID",terser("QRD-8(0)-1"))
      .to("mock:test1");
   // continue processing if extracted field equals a message header
   from("direct:test2")
      .filter(terser("QRD-8(0)-1")
      .isEqualTo(header("PATIENT_ID"))
      .to("mock:test2");

HL7 Validation predicate (Camel 2.11)

Often it is preferable to parse a HL7v2 message and validate it against a HAPI ValidationContext in a separate step afterwards.

Sample:

import static org.apache.camel.component.hl7.HL7.messageConformsTo;
import ca.uhn.hl7v2.validation.impl.DefaultValidation;
...
 
  // Use standard or define your own validation rules
   ValidationContext defaultContext = new DefaultValidation();
 
   // Throws PredicateValidationException if message does not validate
   from("direct:test1").validate(messageConformsTo(defaultContext)).to("mock:test1");

HL7 Acknowledgement expression (Camel 2.11)

A common task in HL7v2 processing is to generate an acknowledgement message as response to an incoming HL7v2 message, e.g. based on a validation result. The ack expression lets us accomplish this very elegantly:

import static org.apache.camel.component.hl7.HL7.messageConformsTo;
import static org.apache.camel.component.hl7.HL7.ack;
import ca.uhn.hl7v2.validation.impl.DefaultValidation;
...
 
  // Use standard or define your own validation rules
   ValidationContext defaultContext = new DefaultValidation();
 
   from("direct:test1")
      .onException(Exception.class)
         .handled(true)
         .transform(ack()) // auto-generates negative ack because of exception in Exchange
         .end()
      .validate(messageConformsTo(defaultContext))
      // do something meaningful here
      ...
      // acknowledgement
      .transform(ack())