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 in <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">tcp://xx.xxx.x.xx:7611</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>
     |--dashboard
           |--dashboard.properties <file>
           |--jaggery <folder>

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

After deploying the toolbox, you can access the HL7 message console in BAM through which you can monitor HL7 messages coming from the ESB.

Log in to BAM management console and click BAM Dashboards menu.
Log in to the dashboard using admin/admin credentials. Any user with admin privileges can log in.
The Message Console Dashboard opens.

Note that if you have multiple dashboards installed, all available ones will be displayed at the top for you to select from. Select the Message Console dashboard.
Enter the connection details to Cassandra cluster and click Login.
- 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

The message search page opens.

The fields of the message search page are described below:

Field	Description
Message type	Stream name to perform the search on. For HL7 messages, select `bam_hl7_data_publisher_store`. This field is mandatory.
Status	Message status (success/failure/all)
Max Rows	Maximum number of search results to be displayed
Start time/End Time	Time interval to search messages

Click Add new condition section to enter more search conditions. An example is given below:
Click the Search Messages icon. Matching results appear on the Search Results page. For example,

You can click,
- The Expand Message icon to view message content
- An activity ID (value is equal to to Message control ID) to view all events that belong to the activity
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,