Configuring HL7 in WSO2 DAS

9 minute read


Some of Its contents may change over time, and subjected to change, I will update on it until I am actively working on it. Because some parts work on manual stuff, which may be corrected/ modified on a future release, don’t bother them at all., If you had the same issue, just follow else leave it to have fun, happy coding.

Just forget about the heading, before DAS implemented there was BAM used in place of DAS, both of them have some similarities but a lot of difference in their features. So Before going to configure with DAS first, we need to try it with BAM. Because for BAM, the things are already run and we need to set up and deploy stuff. No works with coding : smiley: :relaxed:.


Configuring With ESB and BAM.

Products required :- ESB 4.8.1/4.9.0 (latest the best, but don’t try with 5.0.0) and BAM 2.5.0 (last of bam).



I had no clear idea of how this message passes at the beginning, just a rough idea I had so I followed the documentation available in WSO2 ESB and BAM.

  1. First I installed the Axis2 Transport HL7, in ESB with the help of documentation.
  2. Then I enable the HL7 transport, By editing

<ESB-HOME>/repository/conf/axis2/axis2.xml file. as shown in the documentation. That is enabling related transport builder and formatter which used when receiving HL7 message and format it to XML to processing and convert back to the original form using the builder. Next to a transport listener and receivers. these four are disabled in the ESB, we need to enable once we Install HL7 transport.

Don’t enable before Installing it, because it will result in error :smiley: . I hope you guys have understood what I meant.


When doing step 2 for my first try I mistakenly included the parameters for service in axis2.xml file, and with the help of Malith aiya, I correct it and put it into the proxy service I have edited from the one available in Documentation.

  1. Create Proxy Service

For Creating a Customproxy Service, In the main tab of ESB management console, I clicked the proxy service, then choose the custom proxy and thereafter in editor view, I used the code available in the documentation, and edited it to fit to work correctly.

ssl,tcp – this address needs to be edited based on the configuration of offset of DAS Server related ssl, tcp, generally it will be available as https://localhost:9712+offset/ and http://localhost:9612+offset/


Offset Can be configured in <WSO2ANYSERVERHOME>/repository/conf/carbon.xml file just need to change the value for <offset></offset> tag with suitable values without conflict with each other. Otherwise, we can’t run two servers at the same time.

Then it is done with ESB,


We need to configure BAM, it is not configured just deploy carbon toolbox for hl7 which is available in <BAM-HOME>/samples/toolboxes/hl7.tbox. And then goto message console dashboard and select bam_hl7_data_event_store:1.0.0. and choose the choices for the search result and just search values.


I didn’t add many things deeply because you can access these directly from the WSO2 ESB and BAM documentation. I also put the reference in the top of the post, Just look at it if you have any additional queries. (such as, how to deploy toolbox,…)


Finally With ESB 4.9.0 and DAS

Product required :- ESB 4.9.0 and DAS 3.1.0 (not final version)

For this we don’t have any changes in ESB Side, just we need to edit proxy service parameter values to fit the offset of the DAS server.

In DAS we need to create a stream named as bam_hl7_data_event_store:1.0.0, using the JSON file available in BAM, toolbox (when we extract hl7.tbox, it opens to a folder called streamDefn, inside that particular JSON file can be obtained). Then we need to create a receiver based on the streams. Then goto Data Explorer and check the result.

If you tried 1, 2 you won’t get any result set, there are some more things to setup. For this, we additionally use HAPI Test Panel which will send HL7 Message to ESB which has port 9292 opened at ESB, then using proxy service it will send details to hl7acceptor.( this should be initialized by goto <ESB-HOME>/samples/axis2Client/ and try ant hl7accpetor, after replacing a custom build.xml file.). Then the proxy service will publish the data in, out respectively to BAM or ESB based on the configuration you made, and you can observe the result. For DAS, we need to Modify stream, in addition to the given JSON file by adding persistent events that we required to view.


For Real Case, we need to develop a CApps(carbon applications) which should be deployed in DAS and do all these kinds of stuff related to streams and data exploring.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns=""
            <log level="full"/>
            <log level="full"/>
        <endpoint name="endpoint_urn_uuid_9CB8D06C91A1E996796270828144799-1418795938">
            <address uri="hl7://localhost:9988"/>
    <parameter name="transport.hl7.PublisherServerUsername">admin</parameter>
    <parameter name="transport.hl7.PublisherServerPassword">admin</parameter>
    <parameter name="transport.hl7.PublisherEnable">true</parameter>
    <parameter name="transport.hl7.PublisherServerUrl">tcp://</parameter>
    <parameter name="transport.hl7.PublisherSecureServerUrl">ssl://</parameter>
    <parameter name="serviceType">proxy</parameter>
    <parameter name="transport.hl7.Port">9292</parameter>
    <parameter name="transport.hl7.ValidateMessage">true</parameter>

Proxy Service for ESB to DAS/BAM .(offset can be the values of offset for DAS/BAM as of carbon.xml file)

        "name": "bam_hl7_data_publisher_store",
        "version": "1.0.0",
        "nickName": "",
        "description": "",
        "metaData": [
        "name": "host",
        "type": "STRING"
        "name": "server_name",
        "type": "STRING"
        "correlationData": [
        "name": "activity_id",
        "type": "STRING"
        "payloadData": [
        "name": "content",
        "type": "STRING"
        "name": "type",
        "type": "STRING"
        "name": "timestamp",
        "type": "LONG"
        "name": "message_direction",
        "type": "STRING"
        "name": "service_name",
        "type": "STRING"
        "name": "operation_name",
        "type": "STRING"
        "name": "status",
        "type": "STRING"

JSON file correspondence to bam_hl7_data_event_store:1.0.0, No modification, I just included this here for ease of Use.

Don’t get wraps, it not end with here, For me, since ESB 5.0.0 has released I need to configure with that too. There come several issues and problems.

Moving to a new section,


Configuring HL7 Publishing in DAS with ESB 5.0.0

Problem No 01 : Unable to Deploy Proxy service which is exactly same as the one I added above, it causes due to the issue in the version of Business Adaptor HL7 I install ed, for this, I locally create a repo and add the feature connection worked fine after I was successfully deployed, but there comes another problem.


[2016-09-07 10:55:51,716] ERROR - HL7TransportListener Unexpected error when configuring service hl7testproxy for the HL7 transport. It will be disabled for this transport and marked as faulty.

Problem No 02 : This has occurred when I am sending a message through the HAPI Test Panel. For this since no solutions available right now I need to patch the 4.6.6 version to resolve issues, It occurs because of the issue of using bam related instead of das.


[2016-09-09 09:22:46,573] ERROR - ApplicationRouterImpl Attempting to send error message to remote system.

To resolve this generally need to wait for the next version or a patch. For manually doing. (Below parts are based on Jagath Srisikumara Mentoring)

  1. Clone the repository
  2. goto the related location where error occurs,
Caused by: java.lang.NoClassDefFoundError: org/wso2/carbon/bam/data/publisher/util/PublisherUtil

then edit the file named by

Go to <dir>/component/business-adaptors/hl7/

main/java/org/wso2/carbon/business/messaging/hl7/common/data/conf/ and edit file, by replacing bam by das

that is include import; instead of import;

then edit the pom.xml related to <dir>/component/business-adaptors/hl7/

by adding a dependency for das



Small Issue You get If you blindly renaming without any Idea, thus just change das from bam will result in version error when you build the project so beware of it.

[ERROR] The project 1 error
[ERROR] 'dependencies.dependency.version' for is missing.@ line 82, column 21

In the clone repository, on the POM related to Replace




Because groupId has also changed, you can check it with the parent POM file.

And Finally, HL7 Configured With ESB 5.0.0 and DAS 3.1.0.


Working with Patches.

For this process, we need to Set up HL7 Transport, generally in ESB management console. we add features using local repository or repository from an external link. Some time for the latest releases the features from carbon mediation not added/ missed while adding. This can be done by location repository locally.

We need patches when we need to give minor change/update to releases that are generally located in
<PRODUCT-HOME>/repository/component/patches/, here we need to create a repository containing patches for our products. So we create a folder named as patchxxxx where xxxx is a number which is greater than the last patch, if no patch found we can use 1111 or any values, but NOT 0000 because it is the default patch and it defines the initial release. after successfully put the patches. we have to restart the server. and it will run following lines in the terminal which ensures the patch is added and working. Otherwise, we need to check.

[2016-09-09 16:58:32,144]  INFO {org.wso2.carbon.server.extensions.PatchInstaller} -  Patch changes detected
[2016-09-09 16:58:38,550]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Backed up plugins to patch0000