The following samples illustrate how to read/write HL7 messages to/from the file system.
Sending/Receiving HL7 Messages: File System to File System
WSO2 ESB supports transferring messages between HL7 and the file system using HL7 and VFS
transports.
Ensure that you have the VFS and HL7 transports enabled by uncommenting the relevant
transportReceiver and transportSender elements inside the
ESB_HOME/repository/conf/axis2/axis2.xml. You must also uncomment the relevant
builder/formatter pair to enable the ESB to work with the HL7 message format.
Start up the ESB and use the following proxy configuration to get the sample running.
NOTE
Please note this sample uses unix temporary directory /tmp/ in several VFS parameters, please
change these to match a location in your OS file system.
<proxy xmlns="http://ws.apache.org/ns/synapse" name="FileSystemToFileSystem"
transports="vfs">
<target>
<inSequence>
<property name="OUT_ONLY" value="true" scope="default" type="STRING"/>
<property name="transport.vfs.ReplyFileName" expression="getproperty('transport','FILE_NAME')" scope="transport" type="STRING"/>
<log level="full"/>
<send>
<endpoint>
<address uri="vfs:file:///tmp/out"/>
</endpoint>
</send>
</inSequence>
</target>
<parameter name="transport.PollInterval">5</parameter>
<parameter name="transport.vfs.FileURI">/tmp/in</parameter>
<parameter name="transport.vfs.FileNamePattern">.*\.hl7</parameter>
<parameter name="transport.vfs.ContentType">application/edi-hl7;charset="iso-885915"</parameter>
<parameter name="transport.hl7.ValidateMessage">false</parameter>
</proxy>
Place the following HL7 message inside ‘/tmp/in’ folder.
MSH|^~\&|Abc|Def|Ghi|JKL|20131231000000||ADT^A01|1234567|P|2.6|||NE|NE|CH|
The proxy above processes files in ‘/tmp/in’ with *.hl7 file type by invoking the HL7
builders/formatters. The VFS content type specifies the application/edi-hl7 MIME with an optional
charset encoding.
The proxy will build the HL7 message into its equivalent XML format. If you run this example and
place an HL7 message inside /tmp/in, the proxy will print the XML representation of the message
on the WSO2 ESB console and forward the message to the VFS endpoint ‘/tmp/out’.
For more information regarding the various system properties please refer [1]. For VFS transport
properties, please refer [2]. For HL7 transport properties, please refer [3].
Sending/Receiving HL7 Messages: HL7 to FileSystem
The following sample illustrates how we can process files between HL7 transport and the file
system. For this scenario we will use the HAPI Test Panel [4] to send messages to the WSO2
ESB.
Ensure that you have the VFS and HL7 transports enabled by uncommenting the relevant
transportReceiver and transportSender elements inside the
ESB_HOME/repository/conf/axis2/axis2.xml. You must also uncomment the relevant
builder/formatter pair to enable the ESB to work with the HL7 message format.
Start up the ESB and use the following proxy configuration to get the sample running.
NOTE
Please note this sample uses unix temporary directory /tmp/ in several VFS parameters, please
change these to match a location in your OS file system.
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="HL7ToFileSystem"
transports="hl7"
statistics="disable"
trace="disable"
startOnLoad="true">
<target>
<inSequence>
<log level="full"/>
<property name="HL7_RESULT_MODE" value="ACK" scope="axis2"/>
<property name="OUT_ONLY" value="true"/>
<property name="transport.vfs.ReplyFileName"
expression="fn:concat(get-property('SYSTEM_DATE', 'yyyyMMdd.HHmmssSSS'), '.xml')"
scope="transport"/>
<send>
<endpoint>
<address uri="vfs:file:///tmp/out"/>
</endpoint>
</send>
</inSequence>
</target>
<parameter name="transport.hl7.AutoAck">false</parameter>
<parameter name="transport.hl7.Port">55555</parameter>
<parameter name="transport.hl7.ValidateMessage">false</parameter>
<description/>
</proxy>
When the proxy above deploys, a HL7 service will start listening on the port defined in the
transport.hl7.Port service parameter. On arrival of a HL7 message, the proxy will send an ACK
back to the client as specified in the HL7_RESULT_MODE property. In the rest of this scenario,
the HL7 message will be processed through the ESB and send to the VFS endpoint, which will
save the HL7 message in ‘/tmp/out’.
To invoke this proxy you can use the HAPI Test Panel [4] to connect to the HL7 service at the
specified port and send a test message. The client will receive an ACK message in reply from the
HL7 proxy.
For more information regarding the various system properties please refer [1]. For VFS transport
properties, please refer [2]. For HL7 transport properties, please refer [3].
Sending/Receiving HL7 Messages: FTP to HL7
The following sample illustrates how we can process files between HL7 transport and files
accessed through FTP using HL7 and VFS transports.
Ensure that you have the VFS and HL7 transports enabled by uncommenting the relevant
transportReceiver and transportSender elements inside the
ESB_HOME/repository/conf/axis2/axis2.xml. You must also uncomment the relevant
builder/formatter pair to enable the ESB to work with the HL7 message format.
For this sample you will need an HL7 endpoint. To start the sample endpoint please follow the
instructions at [5] and start a new receiving connection on port 9988.
Once you have the HL7 sample endpoint up, start up the ESB and use the following proxy
configuration to get the sample running.
<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="SFTPToHL7"
transports="vfs"
statistics="disable"
trace="disable"
startOnLoad="true">
<target>
<inSequence>
<property name="OUT_ONLY" value="true" scope="default" type="STRING"/>
<log level="full"/>
<send>
<endpoint>
<address uri="hl7://localhost:9988"/>
</endpoint>
</send>
</inSequence>
<outSequence>
<drop/>
</outSequence>
</target>
<parameter name="transport.vfs.ReconnectTimeout">2</parameter>
<parameter name="transport.vfs.ActionAfterProcess">MOVE</parameter>
<parameter name="transport.PollInterval">5</parameter>
<parameter name="transport.hl7.AutoAck">false</parameter>
<parameter name="transport.vfs.MoveAfterProcess">vfs:sftp://user:pass@localhost/vfs/out</parameter>
<parameter name="transport.vfs.FileURI">vfs:sftp://user:pass@localhost/vfs/in</parameter>
<parameter name="transport.vfs.MoveAfterFailure">vfs:sftp://user:pass@localhost/vfs/failed</parameter>
<parameter name="transport.vfs.FileNamePattern">.*\.hl7</parameter>
<parameter name="transport.vfs.ContentType">application/edi-hl7;charset="iso-8859-15"</parameter>
<parameter name="transport.vfs.ActionAfterFailure">MOVE</parameter>
<parameter name="transport.hl7.ValidateMessage">false</parameter>
<description/>
</proxy>
Place the following HL7 message inside the FTP folder defined in the transport.vfs.FileURI
parameter.
MSH|^~\&|Abc|Def|Ghi|JKL|20131231000000||ADT^A01|1234567|P|2.6|||NE|NE|CH|
The VFS proxy will pick files in this directory with *.hl7 extension and send it to the HL7 endpoint
defined.
HL7 Message Log and Replay
From HL7 version 4.2.1 (point to NEW p2repo) a new message store implementation based on
Open JPA has been introduced together with an HL7 console. These components combine to
provide an audit and message replay mechanism.
The following samples illustrates how this is carried out in practice.
Ensure that you have the HL7 transport enabled by uncommenting the relevant transportReceiver
and transportSender elements inside the ESB_HOME/repository/conf/axis2/axis2.xml. You must
also uncomment the relevant builder/formatter pair to enable the ESB to work with the HL7
message format.
The HL7 store is a custom message store implementation on top of Open JPA. The only
requirement is to create an empty database in the desired DBMS and point to this database in the
connection properties.
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
<proxy name="HL7Store" startOnLoad="true" trace="disable" transports=”hl7”>
<description/>
<target>
<inSequence>
<property name="HL7_RESULT_MODE" value="ACK" scope="axis2"/>
<log level="full"/>
<property name="messageType" value="application/edi-hl7" scope="axis2"/>
<clone>
<target sequence="StoreSequence"/>
<target sequence="SendSequence"/>
</clone>
</inSequence>
</target>
<parameter name="transport.hl7.AutoAck">false</parameter>
<parameter name="transport.hl7.Port">55557</parameter>
<parameter name="transport.hl7.ValidateMessage">false</parameter>
</proxy>
<sequence name="StoreSequence">
<property name="OUT_ONLY" value="true"/>
<store messageStore="HL7StoreJPA"/>
</sequence>
<sequence name="SendSequence">
<in>
<send>
<endpoint>
<address uri="hl7://localhost:9988"/>
</endpoint>
</send>
</in>
<out>
<log level="full"/>
<drop/>
</out>
</sequence>
<messageStore class="org.wso2.carbon.business.messaging.hl7.store.jpa.JPAStore"
name="HL7StoreJPA">
<parameter name="openjpa.ConnectionDriverName">org.apache.commons.dbcp.BasicDataSource</parameter>
<parameter name="openjpa.ConnectionProperties">DriverClassName=com.mysql.jdbc.Driver,
Url=jdbc:mysql://localhost/hl7storejpa,
MaxActive=100,
MaxWait=10000,
TestOnBorrow=true, Username=root,
Password=root</parameter>
<parameter name="openjpa.jdbc.DBDictionary">blobTypeName=LONGBLOB</parameter>
</messageStore>
</definitions>
When the proxy above deploys, a HL7 service will start listening on the port defined in the
transport.hl7.Port service parameter. On arrival of a HL7 message, the proxy will send an ACK
back to the client as specified in the HL7_RESULT_MODE property. The clone mediator is used
inside the proxy to replicate the message into the Send and Store sequences, where the message
is sent to the specified endpoint and is also stored in the message store HL7StoreJPA.
is a custom message store implemented in
org.wso2.carbon.business.messaging.hl7.store.jpa.JPAStore and it takes as parameters Open JPA properties.
In this sample the openjpa.ConnectionProperties and openjpa.ConnectionDriverName properties are used to
create a Apache DBCP pooled connection set to a MySQL database. You will need to create the
database specified in the connection properties and provide the database authentication
details matching your database. You may also require to place the JDBC drivers for your
database into $ESB_HOME/repository/components/lib. For more information on the available
Open JPA properties, please refer [8].
HL7StoreJPA
The messages stored in this message store can be viewed using the HL7 Console UI. You can
search for messages on the unique message UUID or HL7 specific Control ID. The search field
supports the wildcard ‘%’ to allow LIKE queries. The table can also be filtered to search for
content within messages.
Selected messages can be edited and injected into a proxy service. Reinjecting a message to the
same service will result in a new message being stored with a different message UUID.
New HL7 Service Parameters
transport.hl7.corePoolSize - defines the core pool size for the transport listener thread pool.
Default value is 100.
transport.hl7.maxPoolSize - defines the max pool size for the transport listener thread pool.
Default value is 200.
transport.hl7.idleThreadKeepAlive - defines the keep alive time in milliseconds for idle threads
in thread pool. Default value is 10000 ms.
transport.hl7.BuildInvalidMessages - this works when transport.hl7.ValidateMessage is set to
false. In the event HL7 transport recieves a message that is not valid, and
transport.hl7.ValidateMessage is set to false, then the WSO2 ESB will build a SOAP envelope
with the contents of the raw HL7 message inside the <rawMessage> element.
transport.hl7.PassThroughInvalidMessages - this works when transport.hl7.ValidateMessage
is set to false and transport.hl7.BuildInvalidMessage is set to true. This forces the WSO2 ESB to
pass through raw invalid HL7 messages received.
The following diagram illustrates these flows.
[1] http://docs.wso2.org/display/ESB480/Properties+Reference
[2] http://docs.wso2.org/display/ESB480/VFS+Transport
[3] http://docs.wso2.org/display/ESB480/HL7+Transport
[4] http://hl7api.sourceforge.net/hapi-testpanel/index.html
[5] - HL7 Sample Endpoint Instructions:
To start an HL7 Endpoint we can use the HAPI Test Panel (http://hl7api.sourceforge.net/hapitestpanel/). We can add a “Receiving Connection” on the required port and start this on the HAPI
Test Panel. HL7 messages sent to this endpoint will be received and visible on the HAPI Test
Panel.
[6] - http://openjpa.apache.org/builds/1.0.1/apache-openjpa1.0.1/docs/manual/ref_guide_conf_openjpa.html