Skip to end of metadata
Go to start of metadata

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

  1. Download WSO2 ESB from http://wso2.com/products/enterprise-service-bus.
  2. 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:

ConfigurationXML 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:

     |--streamDefn <folder>
           |--hl7_data_publisher_def <file>
           |--streams.properties <file>
           |--dashboard.properties <file>
           |--jaggery <folder>

The contents of the toolbox are described below:

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.

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,

  1. Log in to the BAM management console and select Add under BAM Toolbox menu. 

  2. 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.

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

    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.  
  4. 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
  5. The message search page opens.

    The fields of the message search page are described below:


    Message type

    Stream name to perform the search on. For HL7 messages, select bam_hl7_data_publisher_store. This field is mandatory.


    Message status (success/failure/all)

    Max Rows

    Maximum number of search results to be displayed
    Start time/End TimeTime interval to search messages

  6. Click Add new condition section to enter more search conditions. An example is given below:
  7.   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   
  8.  To see details of the HL7 messages in BAM, connect to the Cassandra cluster using the Cassandra Explorer , and browse keyspace bam_hl7_data_publisher_store -> event_ks. For example,


  • No labels