camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > HL7
Date Mon, 12 Jul 2010 04:49:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/HL7">HL7</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~mrt1nz">Martin
Krasser</a>
    </h4>
        <br/>
                         <h4>Changes (3)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{include:HL7 DataFormat} <br>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Message Headers <br>The *unmarshal* operation adds these MSH fields as headers on the
Camel message: <br> <br>h4. Camel 1.x <br>|| Key || MSH field || Example
|| <br>| {{hl7.msh.sendingApplication}} | {{MSH-3}} | {{MYSERVER}} | <br>| {{hl7.msh.sendingFacility}}
| {{MSH-4}} | {{MYSERVERAPP}} | <br>| {{hl7.msh.receivingApplication}} | {{MSH-5}} |
{{MYCLIENT}} | <br>| {{hl7.msh.receivingFacility}} | {{MSH-6}} | {{MYCLIENTAPP}} | <br>|
{{hl7.msh.timestamp}} | {{MSH-7}} | {{20071231235900}} | <br>| {{hl7.msh.security}}
| {{MSH-8}} | {{null}} | <br>| {{hl7.msh.messageType}} | {{MSH-9-1}} | {{ADT}} | <br>|
{{hl7.msh.triggerEvent}} | {{MSH-9-2}} | {{A01}} | <br>| {{hl7.msh.messageControl}}
| {{MSH-10}} | {{1234}} | <br>| {{hl7.msh.processingId}} | {{MSH-11}} | {{P}} | <br>|
{{hl7.msh.versionId}} | {{MSH-12}} | {{2.4}} | <br> <br>h4. Camel 2.0 <br>||
Key || MSH field || Example || <br>| {{CamelHL7SendingApplication}} | {{MSH-3}} | {{MYSERVER}}
| <br>| {{CamelHL7SendingFacility}} | {{MSH-4}} | {{MYSERVERAPP}} | <br>| {{CamelHL7ReceivingApplication}}
| {{MSH-5}} | {{MYCLIENT}} | <br>| {{CamelHL7ReceivingFacility}} | {{MSH-6}} | {{MYCLIENTAPP}}
| <br>| {{CamelHL7Timestamp}} | {{MSH-7}} | {{20071231235900}} | <br>| {{CamelHL7Security}}
| {{MSH-8}} | {{null}} | <br>| {{CamelHL7MessageType}} | {{MSH-9-1}} | {{ADT}} | <br>|
{{CamelHL7TriggerEvent}} | {{MSH-9-2}} | {{A01}} | <br>| {{CamelHL7MessageControl}}
| {{MSH-10}} | {{1234}} | <br>| {{CamelHL7ProcessingId}} | {{MSH-11}} | {{P}} | <br>|
{{CamelHL7VersionId}} | {{MSH-12}} | {{2.4}} | <br> <br>All headers are {{String}}
types. If a header value is missing, its value is {{null}}. <br> <br>h3. Options
<br>The HL7 Data Format supports the following options: <br> <br>|| Option
|| Default || Description || <br>| validate | true | *Camel 2.0*: Whether the HAPI Parser
should validate. | <br> <br>h3. Dependencies <br> <br>To use HL7 in
your camel routes you need to add a dependency on *camel-hl7*, which implements this data
format.  <br> <br>If you use Maven, you could just add the following to your {{pom.xml}},
substituting the version number for the latest &amp; greatest release (see [the download
page for the latest versions|Download]). <br> <br>{code} <br>&lt;dependency&gt;
<br>  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt; <br>  &lt;artifactId&gt;camel-hl7&lt;/artifactId&gt;
<br>  &lt;version&gt;2.2.0&lt;/version&gt; <br>&lt;/dependency&gt;
<br>{code} <br> <br>Since HAPI 0.6, the library has been split into a [base
library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-base/1.0/] and several structures
libraries, one for each HL7v2 message version: <br> <br>* [v2.1 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v21/1.0/]
<br>* [v2.2 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v22/1.0/]
<br>* [v2.3 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v23/1.0/]
<br>* [v2.3.1 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v231/1.0/]
<br>* [v2.4 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v24/1.0/]
<br>* [v2.5 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v24/1.0/]
<br>* [v2.5.1 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v251/1.0/]
<br>* [v2.6 structures library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v26/1.0/]
<br> <br>By default {{camel-hl7}} only references the HAPI [base library|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-base/1.0/].
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: <br> <br>{code} <br>&lt;dependency&gt; <br>
   &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt; <br>    &lt;artifactId&gt;hapi-structures-v24&lt;/artifactId&gt;
<br>    &lt;version&gt;1.0&lt;/version&gt; <br>&lt;/dependency&gt;
<br>&lt;dependency&gt; <br>    &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt;
<br>    &lt;artifactId&gt;hapi-structures-v25&lt;/artifactId&gt; <br>
   &lt;version&gt;1.0&lt;/version&gt; <br>&lt;/dependency&gt;
<br>{code} <br> <br>h4. OSGi <br> <br>An OSGi bundle containing
the base library, all structures libraries and required dependencies (on the bundle classpath)
can be downloaded from the [HAPI Maven repository|http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-osgi-base/]
as well.  <br> <br>{code} <br>&lt;dependency&gt; <br>    &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt;
<br>    &lt;artifactId&gt;hapi-osgi-base&lt;/artifactId&gt; <br>
   &lt;version&gt;1.0.1&lt;/version&gt; <br>&lt;/dependency&gt;
<br>{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">2</span><span
class="diff-added-chars"style="background-color: #dfd;">3</span>.</span> Samples
<br></td></tr>
            <tr><td class="diff-unchanged" >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: <br>{snippet:id=e2|lang=java|url=camel/trunk/components/camel-hl7/src/test/java/org/apache/camel/component/hl7/HL7MLLPCodecTest.java}
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >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. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">3</span><span
class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> Sample
using plain String objects <br></td></tr>
            <tr><td class="diff-unchanged" >In this sample we use plain {{String}}
objects as the data format, that we send, process and receive. As the sample is part of a
unit test, there is some code for assertions, but you should be able to understand what happens.
First we send the plain string, {{Hello World}}, to the {{HL7MLLPCodec}} and receive the response
as a plain string, {{Bye World}}. <br>{snippet:id=e1|lang=java|url=camel/trunk/components/camel-hl7/src/test/java/org/apache/camel/component/hl7/HL7MLLPCodecPlainStringTest.java}
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="HL7-HL7Component"></a>HL7 Component</h2>

<p>The <b>hl7</b> component is used for working with the HL7 MLLP protocol
and the <a href="http://www.hl7.org/" class="external-link" rel="nofollow">HL7 model</a>
using the <a href="http://hl7api.sourceforge.net" class="external-link" rel="nofollow">HAPI
library</a>.</p>

<p>This component supports the following:</p>
<ul class="alternate" type="square">
	<li>HL7 MLLP codec for <a href="http://mina.apache.org/" class="external-link" rel="nofollow">Mina</a></li>
	<li>Agnostic data format using either plain String objects or HAPI HL7 model objects.</li>
	<li><a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type
Converter</a> from/to HAPI and String</li>
	<li>HL7 DataFormat using HAPI library</li>
	<li>Even more easy-of-use as its integrated well with the <a href="/confluence/display/CAMEL/MINA"
title="MINA">camel-mina</a> component.</li>
</ul>


<p>Maven users will need to add the following dependency to their <tt>pom.xml</tt>
for this component:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
    &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
    &lt;artifactId&gt;camel-hl7&lt;/artifactId&gt;
    &lt;version&gt;x.x.x&lt;/version&gt;
    &lt;!-- use the same version as your Camel core version --&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h3><a name="HL7-HL7MLLPprotocol"></a>HL7 MLLP protocol</h3>
<p>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. </p>

<p>To expose a HL7 listener service we reuse the existing <a href="/confluence/display/CAMEL/MINA"
title="MINA">camel-mina</a> component where we just use the <tt>HL7MLLPCodec</tt>
as codec.</p>

<p>The HL7 MLLP codec has the following options:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>startByte</tt> </td>
<td class='confluenceTd'> <tt>0x0b</tt> </td>
<td class='confluenceTd'> The start byte spanning the HL7 payload. Is the HL7 default
value of <tt>0x0b</tt> (11 decimal). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>endByte1</tt> </td>
<td class='confluenceTd'> <tt>0x1c</tt> </td>
<td class='confluenceTd'> The first end byte spanning the HL7 payload. Is the HL7 default
value of <tt>0x1c</tt> (28 decimal). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>endByte2</tt> </td>
<td class='confluenceTd'> <tt>0x0d</tt> </td>
<td class='confluenceTd'> The 2nd end byte spanning the HL7 payload. Is the HL7 default
value of <tt>0x0d</tt> (13 decimal). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>charset</tt> </td>
<td class='confluenceTd'> JVM Default </td>
<td class='confluenceTd'> The encoding (is a <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/Charset.html"
class="external-link" rel="nofollow">charset name</a>) to use for the codec. If not
provided, Camel will use the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/Charset.html#defaultCharset()"
class="external-link" rel="nofollow">JVM default Charset</a>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>convertLFtoCR</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> Will convert <tt>\n</tt> to <tt>\r</tt>
(<tt>0x0d</tt>, 13 decimal) as HL7 usually uses <tt>\r</tt> as segment
terminators. The HAPI library requires the use of <tt>\r</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>validate</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> <b>Camel 2.0:</b> Whether HAPI Parser should validate
or not. </td>
</tr>
</tbody></table>
</div>


<h4><a name="HL7-ExposingaHL7listener"></a>Exposing a HL7 listener</h4>
<p>In our Spring XML file, we configure an endpoint to listen for HL7 requests using
TCP:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
        <span class="code-tag">&lt;endpoint id=<span class="code-quote">"hl7listener"</span>
uri=<span class="code-quote">"mina:tcp://localhost:8888?sync=true&amp;amp;codec=hl7codec"</span>/&gt;</span>
</pre>
</div></div>
<p>Notice we configure it to use <a href="/confluence/display/CAMEL/MINA" title="MINA">camel-mina</a>
with TCP on the <tt>localhost</tt> on port <tt>8888</tt>. We use <b>sync=true</b>
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 <b>codec=hl7codec</b>.
Notice that <tt>hl7codec</tt> is just a Spring bean ID, so we could have named
it <tt>mygreatcodecforhl7</tt> or whatever. The codec is also set up in the Spring
XML file:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
    <span class="code-tag">&lt;bean id=<span class="code-quote">"hl7codec"</span>
class=<span class="code-quote">"org.apache.camel.component.hl7.HL7MLLPCodec"</span>&gt;</span>
        <span class="code-tag">&lt;property name=<span class="code-quote">"charset"</span>
value=<span class="code-quote">"iso-8859-1"</span>/&gt;</span>
    <span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>
<p>And here we configure the charset encoding to use, and <tt>iso-8859-1</tt>
is commonly used.</p>

<p>The endpoint <b>hl7listener</b> can then be used in a route as a consumer,
as this java DSL example illustrates:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"hl7socket"</span>).to(<span class="code-quote">"patientLookupService"</span>);
</pre>
</div></div>
<p>This is a very simple route that will listen for HL7 and route it to a service named
<b>patientLookupService</b> that is also a Spring bean ID we have configured in
the Spring XML as:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
    <span class="code-tag">&lt;bean id=<span class="code-quote">"patientLookupService"</span>
class=<span class="code-quote">"com.mycompany.healtcare.service.PatientLookupService"</span>/&gt;</span>
</pre>
</div></div>
<p>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:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class PatientLookupService {
    <span class="code-keyword">public</span> Message lookupPatient(Message input)
<span class="code-keyword">throws</span> HL7Exception {
        QRD qrd = (QRD)input.get(<span class="code-quote">"QRD"</span>);
        <span class="code-object">String</span> patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();

        <span class="code-comment">// find patient data based on the patient id and
create a HL7 model object with the response
</span>        Message response = ... create and set response data
        <span class="code-keyword">return</span> response
    }
</pre>
</div></div>
<p>Notice that this class is just using imports from the HAPI library and <b>none</b>
from Camel.</p>

<h3><a name="HL7-HL7Modelusingjava.lang.String"></a>HL7 Model using java.lang.String</h3>
<p>The HL7MLLP codec uses plain <tt>String</tt> as data format. And Camel
uses <a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type
Converter</a> to convert from/to strings to the HAPI HL7 model objects. However, you
can use the plain <tt>String</tt> objects if you prefer, for instance if you need
to parse the data yourself.</p>

<p>See samples for such an example.</p>

<h3><a name="HL7-HL7ModelusingHAPI"></a>HL7 Model using HAPI</h3>
<p>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.<br/>
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.</p>

<p>The ER7 sample below is a request to lookup a patient with the patient ID, <tt>0101701234</tt>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MSH|^~\\&amp;|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4
QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||
</pre>
</div></div>

<p>Using the HL7 model we can work with the data as a <tt>ca.uhn.hl7v2.model.Message.Message</tt>
object.<br/>
To retrieve the patient ID for the patient in the ER7 above, you can do this in java code:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Message msg = exchange.getIn().getBody(Message.class);
QRD qrd = (QRD)msg.get(<span class="code-quote">"QRD"</span>);
<span class="code-object">String</span> patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();
</pre>
</div></div>

<p>Camel has built-in type converters, so when this operation is invoked:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Message msg = exchange.getIn().getBody(Message.class);
</pre>
</div></div>
<p>Camel will convert the received HL7 data from <tt>String</tt> to <tt>Message</tt>.
This is powerful when combined with the HL7 listener, then you as the end-user don't have
to work with <tt>byte[]</tt>, <tt>String</tt> or any other simple
object formats. You can just use the HAPI HL7 model objects.</p>

<h3><a name="HL7-HL7DataFormat"></a>HL7 DataFormat</h3>
<p>The <a href="/confluence/display/CAMEL/HL7" title="HL7">HL7</a> component
ships with a HL7 data format that can be used to format between <tt>String</tt>
and HL7 model objects. </p>
<ul class="alternate" type="square">
	<li><tt>marshal</tt> = from Message to byte stream (can be used when returning
as response using the HL7 MLLP codec)</li>
	<li><tt>unmarshal</tt> = from byte stream to Message (can be used when
receiving streamed data from the HL7 MLLP</li>
</ul>


<p>To use the data format, simply instantiate an instance and invoke the marhsal or
unmarshl operation in the route builder:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  DataFormat hl7 = <span class="code-keyword">new</span> HL7DataFormat();
  ...
  from(<span class="code-quote">"direct:hl7in"</span>).marshal(hl7).to(<span
class="code-quote">"jms:queue:hl7out"</span>);
</pre>
</div></div>
<p>In the sample above, the HL7 is marshalled from a HAPI Message object to a byte stream
and put on a JMS queue.<br/>
The next example is the opposite:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  DataFormat hl7 = <span class="code-keyword">new</span> HL7DataFormat();
  ...
  from(<span class="code-quote">"jms:queue:hl7out"</span>).unmarshal(hl7).to(<span
class="code-quote">"patientLookupService"</span>);
</pre>
</div></div>
<p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our
patient lookup service.</p>

<p>Notice there is a shorthand syntax in Camel for well-known data formats that is commonly
used.<br/>
Then you don't need to create an instance of the <tt>HL7DataFormat</tt> object:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  from(<span class="code-quote">"direct:hl7in"</span>).marshal().hl7().to(<span
class="code-quote">"jms:queue:hl7out"</span>);
  from(<span class="code-quote">"jms:queue:hl7out"</span>).unmarshal().hl7().to(<span
class="code-quote">"patientLookupService"</span>);
</pre>
</div></div>

<h3><a name="HL7-MessageHeaders"></a>Message Headers</h3>
<p>The <b>unmarshal</b> operation adds these MSH fields as headers on the
Camel message:</p>

<h4><a name="HL7-Camel1.x"></a>Camel 1.x</h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Key </th>
<th class='confluenceTh'> MSH field </th>
<th class='confluenceTh'> Example </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.sendingApplication</tt> </td>
<td class='confluenceTd'> <tt>MSH-3</tt> </td>
<td class='confluenceTd'> <tt>MYSERVER</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.sendingFacility</tt> </td>
<td class='confluenceTd'> <tt>MSH-4</tt> </td>
<td class='confluenceTd'> <tt>MYSERVERAPP</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.receivingApplication</tt> </td>
<td class='confluenceTd'> <tt>MSH-5</tt> </td>
<td class='confluenceTd'> <tt>MYCLIENT</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.receivingFacility</tt> </td>
<td class='confluenceTd'> <tt>MSH-6</tt> </td>
<td class='confluenceTd'> <tt>MYCLIENTAPP</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.timestamp</tt> </td>
<td class='confluenceTd'> <tt>MSH-7</tt> </td>
<td class='confluenceTd'> <tt>20071231235900</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.security</tt> </td>
<td class='confluenceTd'> <tt>MSH-8</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.messageType</tt> </td>
<td class='confluenceTd'> <tt>MSH-9-1</tt> </td>
<td class='confluenceTd'> <tt>ADT</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.triggerEvent</tt> </td>
<td class='confluenceTd'> <tt>MSH-9-2</tt> </td>
<td class='confluenceTd'> <tt>A01</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.messageControl</tt> </td>
<td class='confluenceTd'> <tt>MSH-10</tt> </td>
<td class='confluenceTd'> <tt>1234</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.processingId</tt> </td>
<td class='confluenceTd'> <tt>MSH-11</tt> </td>
<td class='confluenceTd'> <tt>P</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>hl7.msh.versionId</tt> </td>
<td class='confluenceTd'> <tt>MSH-12</tt> </td>
<td class='confluenceTd'> <tt>2.4</tt> </td>
</tr>
</tbody></table>
</div>


<h4><a name="HL7-Camel2.0"></a>Camel 2.0</h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Key </th>
<th class='confluenceTh'> MSH field </th>
<th class='confluenceTh'> Example </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7SendingApplication</tt> </td>
<td class='confluenceTd'> <tt>MSH-3</tt> </td>
<td class='confluenceTd'> <tt>MYSERVER</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7SendingFacility</tt> </td>
<td class='confluenceTd'> <tt>MSH-4</tt> </td>
<td class='confluenceTd'> <tt>MYSERVERAPP</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7ReceivingApplication</tt> </td>
<td class='confluenceTd'> <tt>MSH-5</tt> </td>
<td class='confluenceTd'> <tt>MYCLIENT</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7ReceivingFacility</tt> </td>
<td class='confluenceTd'> <tt>MSH-6</tt> </td>
<td class='confluenceTd'> <tt>MYCLIENTAPP</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7Timestamp</tt> </td>
<td class='confluenceTd'> <tt>MSH-7</tt> </td>
<td class='confluenceTd'> <tt>20071231235900</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7Security</tt> </td>
<td class='confluenceTd'> <tt>MSH-8</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7MessageType</tt> </td>
<td class='confluenceTd'> <tt>MSH-9-1</tt> </td>
<td class='confluenceTd'> <tt>ADT</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7TriggerEvent</tt> </td>
<td class='confluenceTd'> <tt>MSH-9-2</tt> </td>
<td class='confluenceTd'> <tt>A01</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7MessageControl</tt> </td>
<td class='confluenceTd'> <tt>MSH-10</tt> </td>
<td class='confluenceTd'> <tt>1234</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7ProcessingId</tt> </td>
<td class='confluenceTd'> <tt>MSH-11</tt> </td>
<td class='confluenceTd'> <tt>P</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelHL7VersionId</tt> </td>
<td class='confluenceTd'> <tt>MSH-12</tt> </td>
<td class='confluenceTd'> <tt>2.4</tt> </td>
</tr>
</tbody></table>
</div>


<p>All headers are <tt>String</tt> types. If a header value is missing,
its value is <tt>null</tt>.</p>

<h3><a name="HL7-Options"></a>Options</h3>
<p>The HL7 Data Format supports the following options:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> validate </td>
<td class='confluenceTd'> true </td>
<td class='confluenceTd'> <b>Camel 2.0</b>: Whether the HAPI Parser should
validate. </td>
</tr>
</tbody></table>
</div>


<h3><a name="HL7-Dependencies"></a>Dependencies</h3>

<p>To use HL7 in your camel routes you need to add a dependency on <b>camel-hl7</b>,
which implements this data format. </p>

<p>If you use Maven, you could just add the following to your <tt>pom.xml</tt>,
substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download"
title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-hl7&lt;/artifactId&gt;
  &lt;version&gt;2.2.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<p>Since HAPI 0.6, the library has been split into a <a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-base/1.0/"
class="external-link" rel="nofollow">base library</a> and several structures libraries,
one for each HL7v2 message version:</p>

<ul>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v21/1.0/"
class="external-link" rel="nofollow">v2.1 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v22/1.0/"
class="external-link" rel="nofollow">v2.2 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v23/1.0/"
class="external-link" rel="nofollow">v2.3 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v231/1.0/"
class="external-link" rel="nofollow">v2.3.1 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v24/1.0/"
class="external-link" rel="nofollow">v2.4 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v24/1.0/"
class="external-link" rel="nofollow">v2.5 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v251/1.0/"
class="external-link" rel="nofollow">v2.5.1 structures library</a></li>
	<li><a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-structures-v26/1.0/"
class="external-link" rel="nofollow">v2.6 structures library</a></li>
</ul>


<p>By default <tt>camel-hl7</tt> only references the HAPI <a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-base/1.0/"
class="external-link" rel="nofollow">base library</a>. 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:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
    &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt;
    &lt;artifactId&gt;hapi-structures-v24&lt;/artifactId&gt;
    &lt;version&gt;1.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt;
    &lt;artifactId&gt;hapi-structures-v25&lt;/artifactId&gt;
    &lt;version&gt;1.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h4><a name="HL7-OSGi"></a>OSGi</h4>

<p>An OSGi bundle containing the base library, all structures libraries and required
dependencies (on the bundle classpath) can be downloaded from the <a href="http://hl7api.sourceforge.net/m2/ca/uhn/hapi/hapi-osgi-base/"
class="external-link" rel="nofollow">HAPI Maven repository</a> as well. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
    &lt;groupId&gt;ca.uhn.hapi&lt;/groupId&gt;
    &lt;artifactId&gt;hapi-osgi-base&lt;/artifactId&gt;
    &lt;version&gt;1.0.1&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h3><a name="HL7-Samples"></a>Samples</h3>
<p>In the following example we send a HL7 request to a HL7 listener and retrieves a
response. We use plain <tt>String</tt> types in this example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-object">String</span> line1 = <span
class="code-quote">"MSH|^~\\&amp;|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4"</span>;
<span class="code-object">String</span> line2 = <span class="code-quote">"QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||"</span>;

StringBuilder in = <span class="code-keyword">new</span> StringBuilder();
in.append(line1);
in.append(<span class="code-quote">"\n"</span>);
in.append(line2);

<span class="code-object">String</span> out = (<span class="code-object">String</span>)template.requestBody(<span
class="code-quote">"mina:tcp:<span class="code-comment">//127.0.0.1:8888?sync=<span
class="code-keyword">true</span>&amp;codec=#hl7codec"</span>, in.toString());</span>
</pre>
</div></div>

<p>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 <tt>hl7service</tt> = for instance using Spring and letting the bean id = <tt>hl7service</tt>.</p>

<p>Our business logic is a plain POJO only using the HAPI library so we have these operations
defined:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyHL7BusinessLogic
{

    <span class="code-comment">// This is a plain POJO that has NO imports whatsoever
on Apache Camel.
</span>    <span class="code-comment">// its a plain POJO only importing the HAPI
library so we can much easier work with the HL7 format.
</span>
    <span class="code-keyword">public</span> Message handleA19(Message msg) <span
class="code-keyword">throws</span> Exception {
        <span class="code-comment">// here you can have your business logic <span
class="code-keyword">for</span> A19 messages
</span>        assertTrue(msg <span class="code-keyword">instanceof</span>
QRY_A19);
        <span class="code-comment">// just <span class="code-keyword">return</span>
the same dummy response
</span>        <span class="code-keyword">return</span> createADR19Message();
    }

    <span class="code-keyword">public</span> Message handleA01(Message msg) <span
class="code-keyword">throws</span> Exception {
        <span class="code-comment">// here you can have your business logic <span
class="code-keyword">for</span> A01 messages
</span>        assertTrue(msg <span class="code-keyword">instanceof</span>
ADT_A01);
        <span class="code-comment">// just <span class="code-keyword">return</span>
the same dummy response
</span>        <span class="code-keyword">return</span> createADT01Message();
    }
}
</pre>
</div></div>

<p>Then we set up the Camel routes using the <tt>RouteBuilder</tt> as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">DataFormat hl7 = <span class="code-keyword">new</span>
HL7DataFormat();
<span class="code-comment">// we setup or HL7 listener on port 8888 (using the hl7codec)
and in sync mode so we can <span class="code-keyword">return</span> a response
</span>from(<span class="code-quote">"mina:tcp:<span class="code-comment">//127.0.0.1:8888?sync=<span
class="code-keyword">true</span>&amp;codec=#hl7codec"</span>)
</span>    <span class="code-comment">// we use the HL7 data format to unmarshal
from HL7 stream to the HAPI Message model
</span>    <span class="code-comment">// <span class="code-keyword">this</span>
ensures that the camel message has been enriched with hl7 specific headers to
</span>    <span class="code-comment">// make the routing much easier (see below)
</span>    .unmarshal(hl7)
    <span class="code-comment">// using choice as the content base router
</span>    .choice()
        <span class="code-comment">// where we choose that A19 queries invoke the handleA19
method on our hl7service bean
</span>        .when(header(<span class="code-quote">"CamelHL7TriggerEvent"</span>).isEqualTo(<span
class="code-quote">"A19"</span>))
            .beanRef(<span class="code-quote">"hl7service"</span>, <span class="code-quote">"handleA19"</span>)
            .to(<span class="code-quote">"mock:a19"</span>)
        <span class="code-comment">// and A01 should invoke the handleA01 method on
our hl7service bean
</span>        .when(header(<span class="code-quote">"CamelHL7TriggerEvent"</span>).isEqualTo(<span
class="code-quote">"A01"</span>)).to(<span class="code-quote">"mock:a01"</span>)
            .beanRef(<span class="code-quote">"hl7service"</span>, <span class="code-quote">"handleA01"</span>)
            .to(<span class="code-quote">"mock:a19"</span>)
        <span class="code-comment">// other types should go to mock:unknown
</span>        .otherwise()
            .to(<span class="code-quote">"mock:unknown"</span>)
    <span class="code-comment">// end choice block
</span>    .end()
    <span class="code-comment">// marhsal response back
</span>    .marshal(hl7);
</pre>
</div></div>

<p>Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields
preconfigued on the Camel Message. This lets us much more easily define our routes using the
fluent builders.<br/>
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.</p>

<h4><a name="HL7-SampleusingplainStringobjects"></a>Sample using plain String
objects</h4>
<p>In this sample we use plain <tt>String</tt> objects as the data format,
that we send, process and receive. As the sample is part of a unit test, there is some code
for assertions, but you should be able to understand what happens. First we send the plain
string, <tt>Hello World</tt>, to the <tt>HL7MLLPCodec</tt> and receive
the response as a plain string, <tt>Bye World</tt>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">MockEndpoint mock = getMockEndpoint(<span class="code-quote">"mock:result"</span>);
mock.expectedBodiesReceived(<span class="code-quote">"Bye World"</span>);

<span class="code-comment">// send plain hello world as <span class="code-object">String</span>
</span><span class="code-object">Object</span> out = template.requestBody(<span
class="code-quote">"mina:tcp:<span class="code-comment">//127.0.0.1:8888?sync=<span
class="code-keyword">true</span>&amp;codec=#hl7codec"</span>, <span
class="code-quote">"Hello World"</span>);
</span>
assertMockEndpointsSatisfied();

<span class="code-comment">// and the response is also just plain <span class="code-object">String</span>
</span>assertEquals(<span class="code-quote">"Bye World"</span>, out);
</pre>
</div></div>

<p>Here we process the incoming data as plain String and send the response also as plain
String:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"mina:tcp:<span class="code-comment">//127.0.0.1:8888?sync=<span
class="code-keyword">true</span>&amp;codec=#hl7codec"</span>)
</span>    .process(<span class="code-keyword">new</span> Processor() {
        <span class="code-keyword">public</span> void process(Exchange exchange)
<span class="code-keyword">throws</span> Exception {
            <span class="code-comment">// use plain <span class="code-object">String</span>
as message format
</span>            <span class="code-object">String</span> body = exchange.getIn().getBody(<span
class="code-object">String</span>.class);
            assertEquals(<span class="code-quote">"Hello World"</span>, body);

            <span class="code-comment">// <span class="code-keyword">return</span>
the response as plain string
</span>            exchange.getOut().setBody(<span class="code-quote">"Bye World"</span>);
        }
    })
    .to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>

<h3><a name="HL7-SeeAlso"></a>See Also</h3>
<ul>
	<li><a href="/confluence/display/CAMEL/Configuring+Camel" title="Configuring Camel">Configuring
Camel</a></li>
	<li><a href="/confluence/display/CAMEL/Component" title="Component">Component</a></li>
	<li><a href="/confluence/display/CAMEL/Endpoint" title="Endpoint">Endpoint</a></li>
	<li><a href="/confluence/display/CAMEL/Getting+Started" title="Getting Started">Getting
Started</a></li>
</ul>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/HL7">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=92354&revisedVersion=17&originalVersion=16">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/HL7?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message