This component supports the following:
Maven users will need to add the following dependency to their
HL7 MLLP protocol
HL7 is often used with the HL7 MLLP protocol, which is a text based TCP socket based protocol. This component ships with a Mina and Netty4 Codec that conforms to the MLLP protocol so you can easily expose an HL7 listener accepting HL7 requests over the TCP transport layer. To expose a HL7 listener service, the camel-mina2 or camel-netty4 component is used with the
HL7 MLLP codec can be configured as follows:
Exposing an HL7 listener using Mina
In the Spring XML file, we configure a mina2 endpoint to listen for HL7 requests using TCP on port
sync=true indicates that this listener is synchronous and therefore will return a HL7 response to the caller. The HL7 codec is setup with codec=#hl7codec. Note that
The endpoint hl7MinaLlistener can then be used in a route as a consumer, as this Java DSL example illustrates:
This is a very simple route that will listen for HL7 and route it to a service named patientLookupService. This is also Spring bean ID, configured in the Spring XML as:
The business logic can be implemented in POJO classes that do not depend on Camel, as shown here:
Exposing an HL7 listener using Netty (available from Camel 2.15 onwards)
In the Spring XML file, we configure a netty4 endpoint to listen for HL7 requests using TCP on port
sync=true indicates that this listener is synchronous and therefore will return a HL7 response to the caller. The HL7 codec is setup with encoder=#hl7encoder and decoder=#hl7decoder. Note that
The endpoint hl7NettyListener can then be used in a route as a consumer, as this Java DSL example illustrates:
HL7 Model using java.lang.String or byte
The HL7 MLLP codec uses plain String as its data format. Camel uses its Type Converter to convert to/from strings to the HAPI HL7 model objects, but you can use the plain String objects if you prefer, for instance if you wish to parse the data yourself.
As of Camel 2.14.1 you can also let both the Mina and Netty codecs use a plain
HL7v2 Model using HAPI
The HL7v2 model uses Java objects from the HAPI library. Using this library, you can encode and decode from the EDI format (ER7) that is mostly used with HL7v2.
The sample below is a request to lookup a patient with the patient ID
Using the HL7 model you can work with a
This is powerful when combined with the HL7 listener, because you don't have to work with
The HL7 component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.
To use the data format, simply instantiate an instance and invoke the marshal or unmarshal operation in the route builder:
In the sample above, the HL7 is marshalled from a HAPI Message object to a byte stream and put on a JMS queue.
Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.
As of HAPI 2.0 (used by Camel 2.11), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling
As of Camel 2.11,
As of Camel 2.14.1, both
There is a shorthand syntax in Camel for well-known data formats that are commonly used.
The unmarshal operation adds these fields from the MSH segment as headers on the Camel message:
All headers except
The HL7 Data Format supports the following options:
To use HL7 in your Camel routes you'll need to add a dependency on camel-hl7 listed above, which implements this data format.
The HAPI library is split into a base library and several structure libraries, one for each HL7v2 message version:
Alternatively, an OSGi bundle containing the base library, all structures libraries and required dependencies (on the bundle classpath) can be downloaded from the central Maven repository.
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.
HL7 Validation predicate
Often it is preferable to first parse a HL7v2 message and in a separate step validate it against a HAPI ValidationContext.
HL7 Validation predicate using the HapiContext (Camel 2.14)
The HAPI Context is always configured with a ValidationContext (or a ValidationRuleBuilder), so you can access the validation rules indirectly. Furthermore, when unmarshalling the HL7DataFormat forwards the configured HAPI context in the
HL7 Acknowledgement expression
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
In the following example, a plain
In the next sample, HL7 requests from the HL7 listener are routed to the business logic, which is implemented as plain POJO registered in the registry as
Then the Camel routes using the
Note that by using the HL7 DataFormat the Camel message headers are populated with the fields from the MSH segment. The headers are particularly useful for filtering or content-based routing as shown in the example above.