Setting up HL7 Data Agent

The HL7 data agent is used to collect and monitor HL7 messages coming from WSO2 ESB. The following sections explain how to configure the HL7 data agent in the ESB and monitor HL7 messages in BAM:

Installing HL7 transport in the ESB

Download WSO2 ESB from http://wso2.com/products/enterprise-service-bus.
Install HL7 transport to WSO2 ESB using Installing the HL7 Transport section in the ESB documentation.

Enabling HL7 data agent in the ESB

HL7 data agent (message publisher) comes by default with the HL7 transport that you installed earlier. To enable the data agent in the ESB and configure it to connect to BAM, set the following parameters within the <axisconfig name="AxisJava2.0"> element in the <ESB_HOME>/repository/conf/axis2/axis2.xml file:

Configuration	XML Code
Enable HL7 data agent	`<parameter name="transport.hl7.PublisherEnable">true</parameter>`
Set the BAM server URL to which the data agent in the ESB connects to	`<parameter name="transport.hl7.PublisherServerUrl">tcp://xx.xxx.x.xx:7611</parameter>` Provide the IP address of your BAM server.
Set the BAM server credentials	`<parameter name="transport.hl7.PublisherServerUsername">admin</parameter>` `<parameter name="transport.hl7.PublisherServerPassword">admin</parameter>`
Set secure authentication. This is optional.	`<parameter name=" transport.hl7.PublisherSecureServerUrl">ssl://xx.xxx.x.xx:7711</parameter>` Provide the IP address of the BAM server.
Enable message status validation (Success or failure)	`<parameter name="transport.hl7.ValidateMessage">true</parameter>` Enable this parameter with the ones above to get the message status.

Deploying the HL7 toolbox in BAM

The HL7 toolbox contains Hive scripts used to analyze HL7 messages. It comes as HL7.tbox file inside <BAM_HOME>/samples/toolboxes folder. The HL7.tbox file has the following structure:

hl7.tbox
     |--streamDefn <folder>
           |--hl7_data_publisher_def <file>
           |--streams.properties <file>

The contents of the toolbox are described below:

File/Folder	Attributes	Description
`hl7_data_publisher_def <file>`		The stream definition to which the HL7 messages are published to.
`streams.properties <file>`		The stream properties.
	`streams.definitions.defn1.customindexes`	Custom indexes that need to be created for the stream attributes found in `hl7_data_publisher_def` file.
	`streams.definitions.defn1.arbitraryindexes`	All HL7 fields are published to BAM as arbitrary fields. Therefore, you mention here all the HL7 fields that need to be indexed as a comma separated with their correct data types. For example, <field1>:<dataType>,<field2>:<dataType>,....,<fieldn>:<dataType>. Be sure to add all the fields before deploying the toolbox. You can only search by the HL7 fields that are mentioned here.
`dashboard <folder>`		This folder contains HL7 message console (jaggery app) and the property file.

To install the toolbox in BAM,

Log in to the BAM management console and select Add under BAM Toolbox menu.
Go to the Custom Toolbox section, select <BAM_HOME>/samples/toolboxes/HL7.tbox file and click Install.
- Deploying the toolbox can take several minutes to complete because a separate index column family is created per each field given in the streams.definitions.defn1.arbitraryindexes and streams.definitions.defn1.customindexes sections. Enable the debug log to see the progress of the deployment and the index CF names per each field.
To modify the toolbox, extract the .tbox as you extract a zip file, add your modifications, archive it back as a .zip and then rename the .zip extension to .tbox.

Monitoring HL7 messages using BAM

Use either BAM message console or Cassandra explorer to monitor the HL7 messages as follows.

Monitoring using BAM message console

After deploying the toolbox, you can access the HL7 message console in BAM through which you can monitor HL7 messages coming from the ESB. For instructions on how to monitor HL7 messages using the BAM message console, see Message Console.

Monitoring using Cassandra explorer

Follow the below steps to monitor HL7 messages using Cassandra explorer.

To see details of the HL7 messages in BAM, select Explore Cluster under Cassandra Explorer menu of the Tools menu in the management console.
Connect to the Cassandra cluster.
- Connection Url* : Connection URL of the Cassandra cluster with IP and port. e.g., localhost:9160. This field is mandatory.
- Username/Password : Credentials of the cluster
- Maximum Result Count : Maximum number of results retrieved from the Cassandra cluster
Browse keyspace bam_hl7_data_publisher_store -> event_ks. For example,