Monday Nov 17, 2008

Making HL7 BC work with Java EE SE

You can use Java for transformation or routing logic instead of BPEL by using one of the two options. One is using Java EE SE and another is POJO SE. A Java EE SE can work as an EJB and can utilise App.Server's services such as transactions, pooling etc. whereas a POJO SE cannot. A Java EE SE acts as a bridge between Java EE and JBI environment. In this blog entry I will you guide you step by step on how to make HL7 BC to interact with Java EE SE.

Inbound Scenario: In this scenario HL7 BC receives a HL7 message (ADT A43) and invokes Java EE SE. Here, we will create an EJB webservice. We will use a WSDL which uses HL7 Binding instead of SOAP binding to create the webservice.

  1. Create a WSDL with HL7 Binding and have it in some location. In this step we will create a Java application project just to create the WSDL. If the WSDL is already created , you can proceed to to Step 2.

    •  Download the HL7 V2 XSDs from and extract it somewhere.

    • Create a New Java Application Project

    • Create a WSDL by clicking on File -> New File _> WSDL document -> choose Concrete WSDL Document -> Choose Binding as HL7 Binding and Click Next.

    • Choose the Request Message by Clicking on Browse -> Selecting the xsd ADT_A43.xsd and choosing the element ADT_A43.CONTENT.

  2. Create an EJB Module :

    • Go To File -> New Project -> Enterprise -> EJB Module. Click Next.

    • Give a project name . Click Next

    • Choose Server as Glassfish V2 and Java EE Version as Java EE 5.

  3. Create an EJB Webservice from the WSDL created from Step 1.

    • Right Click on the EJB Module and choose - > New -> Other -> Webservices -> WebService from WSDL and click Next.

    • Provide a class name and package name for the ejb class and choose the WSDL created in Step 1. Wait for sometime until Web Service Port appears and Click on Finish

  4. Now, you have an EJB java file with one method hl7WsdlOperation(org.hl7.v2xml.ADTA43CONTENT part1). The class org.hl7.v2xml.ADTA43CONTENT is a JAXB generated class. You can use the methods of this class to access the values from received message. If you want invoke another JBI component from this EJB by passing the received message, See the outbound scenario. Now, for testing purpose you can just print the received "part1" object inside the method.

  5. Create a Composite Application and deploy it.

    • Go To File -> New Project -> Service Oriented Architecture -> Composite Application. 

    • Provide a project name and finish the wizard.

    • Double Click on the Service Assembly to open the CASA editor.

    • Drag and drop the EJB Module into the CASA editor.

    • Build and deploy the Composite Application.

Outbound Scenario: In this scenario, we will read the HL7 message from File using File BC, invoke Java EE SE passing the HL7 message into JAXB object and invoke HL7 BC from JavaEE SE passing the JAXB object.

  1. Create a WSDL with File Binding (which uses hl7encoder-1.0) and have it in some location.

    • Download the HL7 V2 XSDs from and extract it somewhere.

    • Create a Java Application Project

    • Create a WSDL by clicking on File -> New File _> WSDL document -> choose Concrete WSDL Document -> Choose Binding as File Binding, Choose Type as Poll and click next.

    • Provide the file name as input.txt and Click on Finish.

    • Open the WSDL Editor. Go to Messages -> PollInputMessage -> part1 .

    • Change the datatype by right clicking and choosing the element ADT_A43.CONTENT from ADT_A43.xsd

    • Traverse the tree to input -> file:message. In the properties sheet, choose use = encoded and provide encodingStyle as hl7-encoder1.0

  2. Create an EJB Module :

    • Go To File -> New Project -> Enterprise -> EJB Module. Click Next.

    • Give a project name . Click Next

    • Choose Server as Glassfish V2 and Java EE Version as Java EE 5.

  3. Create an EJB Webservice from the WSDL created from Step 1.

    • Right Click on the EJB Module and choose - > New -> Other -> Webservices -> WebService from WSDL and click Next.

    • Provide a class name and package name for the ejb class and choose the WSDL created in Step 1. Wait for sometime until Web Service Port appears and Click on Finish

  4. Now you have an EJB class with one method poll(org.hl7.v2xml.ADTA43CONTENT part1) . We need to invoke a webservice from this ejb module. So, create a webservice reference by following these steps:

    • Right Click on the ejb module. Choose Other -> Web Services -> Web Service Client.

    • Select the HL7 WSDL. (To create a HL7 WSDL see the STEP 1 in Inbound scenario). Click Finish

  5. Now, you can see a new folder created called Web Service References. Expand it until you see the operation. Drag and drop the operation into the ejb poll method. You will have code created for invoking the webservice. You need to marshall the JAXB object into XML string and pass the string for the method invocation. The code snippet should look like this: Code Snippet

  6. Create a Composite Application and deploy it.

    • Go To File -> New Project -> Service Oriented Architecture -> Composite Application. 

    • Provide a project name and finish the wizard.

    • Double Click on the Service Assembly to open the CASA editor.

    • Drag and drop the EJB Module into the CASA editor.

    • Build and deploy the Composite Application.

Place the test message in C:\\temp\\input.txt to test.

Thursday Oct 30, 2008

MLLP V2 support in HL7 Binding Component

We recently added MLLP Version 2 support in HL7 BC. I would like to share you the details of this support.

What is MLLP?

MLLP stands for Minimal Lower Layer protocol. It is a simple protocol
over TCP-ip. It is represented as : StartBlockChar -> Payload ->
EndBlockChar -> EndDataChar.

What is MLLP V2?

MLLP V2 provides reliability over MLLP transport. It provides
reliability by insisting on persistence of messages and by additional
ack/nak generation over MLLP. For every message received, the systems
should send a commit acknowledgement or negative acknowledgement. The
commit acknowledgement should be sent when the message is successfully
persisted otherwise a negative acknowledgement should be sent. This ack
/ nak is nothing but a single character enveloped within MLLP wrapper.
The MLLP V2 ack/nak will be of the form :

StartBlockChar -> AckChar/NakChar -> EndBlockChar ->EndDataChar.

The StartBlockCharacter is : 11. EndBlockCharacter is 28 End DataChar is 13.

 The characters used for Commit Acknowledgement in hex is 0x06 and negative acknowledgement is 0x15.

MLLP V2 in HL7 BC.

To Configure MLLP V2 in HL7 BC, just select the LLP Type as MLLPV2 in
ProtocolProperties extensibility element. The HL7 messages can be
persisted in a JDBC Datasource or in the HL7 BC's embedded Axion DB.
For storing the messages in JDBC Datasource, the user has to provide
the JNDI name of the JDBC datasource when the HL7 BC is installed. HL7
BC will create the required Tables for persisting the messages. All the
messages are stored in a table called HL7MessageLog. 

If the JNDI name is not found the embedded DB will be used by default.
The embedded Axion db is created in HL7 BC install location in
glassfish. That will be under

Note: The HL7 messages are persisted only in the server side i.e Inbound mode. In outbound case the messages are not persisted.

Structure of HL7MessageLog table.


MESSAGEID VARCHAR(250) - A hash of the entire request message encoded in Byte 64 format.

APPLICATIONID VARCHAR(250) - The application name which stores the message. This will be service assembly name.

REQUESTMESSAGE CLOB - Entire HL7 request message


STATUS SMALLINT - Status of the message. 1 - Request message received, 2. HL7 ACK sent. 3 HL7 NACK sent

CREATEDTIME TIMESTAMP - Created time of the request message

LASTUPDATEDTIME TIMESTAMP - The time when the table was last updated.

Tuesday Aug 07, 2007

Understanding HL7 Version 3 from Developer perspective


Understanding HL7 V3 specification is a difficult task for the developers who worked on HL7 v2 messages. The HL7 V3 specification is different in many ways from V2. I have gathered all the information required for transmitting HL7 V3 messages from the V3 specification documents and here I will give a general overview of different elements of V3 and constructing the V3 message that can be exchanged with other compatible systems.

HL7 V2 versus V3

HL7 V2 is primarily intended for developers or clinical interface specialists, whose job is to move clinical data or create tools to exchange such data from one application to another. Thus, V2 is designed to ease the exchange of clinical data between different systems. Whereas V3 is influenced by Medical informatists who work in the field of healthcare and study how healthcare information is created. Thus the V3 specification primarily focuses on Healthcare data rather than how to transmit the data.

HL7 V3 message development process

The V3 message development process is based on information models produced by the development groups. An information model represents data in object oriented way. It has classes with relationships, properties, states and constraints. The information models are refined and localized to come up with messages that can be exchanged with different systems.

Reference Information Model (RIM): The RIM is an information model collectively developed by the HL7 working group. It is the information model that encompasses the HL7 domain of interest as a whole. The RIM is a coherent, shared information model that is the source for the data content of all HL7 messages. The RIM is intentionally abstract to represent the HL7 data in a standard way across all the domains of Healthcare. It is the root of all information models and structures developed as part of the V3 development process.

Domain-Message Information Model (D-MIM): The classes, attributes, state-machines, and relationships in the RIM are used to derive domain-specific information models called D-MIMs. A D-MIM is a refined subset of the RIM that includes a set of class clones, attributes and relationships that can be used to create messages for a particular domain (a particular area of interest in healthcare). Domains under Administrative Management : - Accounting and Billing - Claims & Reimbursements - Patient Administration - Personnel Management - Scheduling Domains under Health and Clinical Management: - Clinical Document Architecture - Medical Records - Public Health Reporting - Clinical Genomics - Specimen Domain - Regulated Studies

Refined-Message Information Model (R-MIM): The R-MIM is a subset of a D-MIM that is used to express the information content for a message or set of messages with annotations and refinements that are message specific. The D-MIM is used as a common base upon which all R-MIMs within a domain are built.

Heirarchical Message Descriptions (HMDs): The HMDs are abstract message structures which represent the information from R-MIMs. The HMD represents R-MIM in an organized way which can be exchanged between systems. The HMDs are called abstract because they define the message structure without reference to the implementation technology.

XML Schemas: HL7 V3 defines Implementation technology specifications (ITS). These ITS define how the abstract message types should be transmitted using an underlying technology. V3 currently defines XML ITS and UML ITS. The XML ITS defines data types and structures. The XML datatypes represents HL7 datatypes in XML specific way. And the XML structures represent the structures defined by HMDs. Thus for every message type there is a HMD and XSD correspondingly.

Understanding V3 Artifacts: We saw the process of V3 message development, where V3 information models are refined to come up with XML schemas which can be used to construct V3 XML messages. But I didn’t mention which are the XSDs contain all required information to come up with complete V3 message. In the below section, I will address this. To understand the V3 specification, understanding the artifacts of the specification is very important. The HL7 technical committee during the specification development process identifies various artifacts for a particular domain and submits the same. For every domain, the artifacts are organized in the same structure. Thus for every domain specification, the committee submits the artifacts documented as explained below. To identify every artifact, the HL7 has come up with an unique attribute called Artifact Identifier. For example, an application role submitted by the Patient Administration domain will have the following unique artifact identifier: PRPA_AR00001UV00 Where: PR = Practice(Subsection) PA = Patient Administration (Domain) AR = Application Role (Artifact type) 00001 = 6 digit non-meaningful number assigned by the Technical Comittee to ensure uniqueness UV = Realm (the only current value is UV for universal) 00 = Current version number

Application Role (Code:AR): Application roles represent a set of communication responsibilities that might be implemented by an application. Thus they describe system components or sub-components that send and/or receive interactions.

Trigger Event (Code:TE): A trigger event is a condition on which an action is initiated. 

Storyboard (Code:ST): A storyboard explains the series of actions in a particular scenario. Its primary purpose is to identify the various scenarios. Each storyboard is represented as sequence diagrams. It also lists the interactions between two or more systems playing different Application Roles.

Storyboard Narrative (Code:SN): A Storyboard narrative provides explanation for the storyboard.

D-MIM (Code:DM): Domain specific classes represented in a diagram with relationships.

R-MIM (Code: RM): A subset of D-MIM classes represented in a diagram with relationships. These classes are specifically to represent information content for one or more HMDs.

HMD (Code:HD): The Message Structures or Message types which form the payload of the data transmitted. The base HMD is depicted in a tabular format or in excel view. It also lists the various message types built based on this HMD.

Message Type (Code:MT): A message type represents a unique set of constraints applied against the common message. It is represented in Table view or in XML schema view.

Interaction (Code:IN): Interactions define the interaction between two systems. The documentation of interaction defines: - Trigger Event which initiated the interaction - Message Type which should be used for interaction (The payload) - Transmission Wrapper: A Message Type to wrap the payload with - Control Act Wrapper: A Message Type to hold the administration information about the payload being transmitted. - Sender: The Sender Role for this interaction - Receiver: The Receiver Role for this interaction.

Transmission Wrapper and Control Act Wrapper: This specification defines HL7 V3 Composite message is composed of:


  1. An "HL7 Transmission wrapper" (always)


  2. A "Trigger Event Control Act" (required for all messages except accept level acknowledgements, for which it is not permitted)


  3. The "HL7 Domain Content" specified by an HL7 domain specific technical committee (required for each Trigger Event Control Act)


The HL7 Transmission wrapper is specified in domain: Transmission Infrastructure. This domain specification describes the details on composing a V3 composite message and exchanging the composite message between systems. It covers features like acknowledgements, sequence no. protocol support, error handling and security. “Trigger Event Control Act” is detailed in domain: Message Control Act Infrastructure. This details the administrative information about the data being transmitted. Thus the interactions define the complete set of information that is required to exchange HL7 data between the systems.

Conclusion: The HL7 V3 specification contains the XSDs for Interactions which can be used to construct the composite HL7 V3 message. This composite message then can be transmitted between the systems. The V3 Specification says that a system can claim for V3 conformance based on the Application Role it will play in a particular domain. The system playing the Application Role will recognize the Trigger Events, the message types and the data content of these messages. Thus a system whose sole responsibility is to exchange the V3 data between systems reliably should claim conformance for the Application Roles defined under Transmission Infrastructure Domain.

Wednesday Apr 04, 2007

Receiving Emails through SMTP BC.

As soon as you see this topic you may think that using SMTP BC you can receive emails as you receive emails in your Inbox. But the case is different here. Using SMTP BC, you can receive email which is destined for your SMTP BC and process the email based on the content.

SMTP BC is Simple Mail Transfer Protocol, which means that this is a protocol defined in RFC 821 for the mail servers defining a standard way to handle the emails. It is also a protocol for communicating with SMTP Servers for email exchanges. So, In a typical scenario when an SMTP Server receives an email it may handle in the following ways:

  •  Check if the destination email ids in the emails are bound to this SMTP Server. If so, store the emails in a location where the email clients can access it.
  •  If the destination email ids are not bound to this email address, but the SMTP Server knows how to route the email to the destination, then reroute the email to the destination.
  •  If it cannot recognize the email id defined, return an error.

Coming back to the SMTP BC case, How is it going to receive the email? Is it going to read it from a mail box? No.

 SMTP BC is implemented in such a way that it will listen in a port (default is 25) specified in the WSDL for incoming emails. That is, it has a built in SMTP Server capability to receive emails. So, what will it do receiving email? Well it just provides the email content to the consumers of the Jbi ecosystem.

As I said, an SMTP Server has to recognize the email ids mentioned in the to,cc,bcc section of an email. But how does the SMTP BC's server recognize the email ids? In a typical scenario, an SMTP Server will have a huge database of email addresses belonging to the domain. But in our case, the SMTP BC recognizes only the email ids defined in the mailto: URL of WSDL extension's smtp:server tag's location attribute.

For eg:

     <wsdl:service name="smtpWSDLService">
        <wsdl:port name="smtpWSDLPort" binding="tns:smtpWSDLBinding">
            <smtp:address location=","/>

The above WSDL defines two email ids: and In this case, the SMTP BC's smtp server can accept emails destined for only these two email ids. If you use your email client to send emails to this smtp server with to ,cc or bcc having any other email ids, the SMTP BC will reject the email.

Here are some of the scenarios I can think of where SMTP BC's inbound case can be helpful.

  1. You want to receive an email, store it somewhere and send an acknowledgement email to the sender.
  2. You want to parse an email which is in a specified format you know and process it. 
  3. Based on the subject of the email you want to organize the emails or forward it to some other email ids.

A demo:

The below demo is a simple scenario where the content and subject of an email is preserved in a file.

Here are the Steps involved:

  1. Create a BPEL Module.
  2. Create a WSDL with SMTP Binding.
  3. Create a WSDL with File Binding.
  4. Create a BPEl process.
  5. Using BPEL Designer draw the flow of activities.
  6. Create a Composite Application project.
  7. Add the Bpel Module to the Composite Application.
  8. Compile and deploy the application.
  9. Use an email client and configure the SMTP server to the SMTP BCs smtp server.
  10. Send an email with to address specified in the WSDL.

You should be able to see the file containg the subject and the content. Here is the demo:

Tuesday Mar 13, 2007

Using SMTP BC to send Email in JBI Environment

What is SMTP BC?

Java Business Integration (JBI) is a standard for integrating business sytems. It defines a platform for different components to interact each other in a standard way. A binding component in a JBI environment is a piece of software written to interact with external systems which typically involves communicating through a specific protocol. Thus SMTP Binding component provides communication to SMTP servers for other JBI components.

How do you send e-mail using SMTP BC?

The SMTP BC currently provides mechanism for sending emails to SMTP servers and it also acts as a SMTP server to receive emails. Here we will see how it helps us to send emails. Here we use NetBeans 5.5.1 IDE to develop a composite application which uses SMTP BC, BPEL SE and HTTP BC to send a mail.

Sample Application:

The sample application we create here involes a http request triggering an email to be sent to a particular email destination. The steps to create are:

  1. Create a BPEL Module project

  2. Create 2 WSDLs. one with Http/SOAP Binding and another with SMTP Binding.

  3. Edit the WSDL with SMTP Binding to specify the destination email address, SMTP Server to use and the message part for content of the email.

  4. Create a BPEL Process.

  5. Build the module to create a Service Unit.

  6. Create a Composite Application.

  7. Add the above BPEL Module to the composite application.

  8. Build the Composite Application to a Service Assembly.

  9. Start the App.Server and deploy the composite application.

  10. Test the application.

How to Create the WSDL With SMTP Binding:

Here we will use the WSDL Wizard for creating the WSDLs:

1. In the BPEL Module Project, Right Click on Process Files folder and select New - > File/Folder. Select the Folder XML and then WSDL Document from Right pane.

2. Provide a Name for WSDL. In this sample, we are not going to use any Schemas, so leave it as blank. Click Next.

3. Select the Operation type as One-Way Operation. And leave the other values to default. Click Next.

4. Select SMTP Binding in the "Concrete Configuration" Screen. Click Finish.

Providing values for smtp:address :

1. Open the SMTPWSDL using WSDL Editor
2. Expand the folder: Services -> SMTPWSDLService -> SMTPWSDLPort -> smtp:address
3. Provide the values in property editor for location and smtpserver attributes.

Providing values for smtp:input :

1. Open the SMTPWSDL using WSDL Editor.
2. Expand the folder : Bindings -> SMTPWSDLBinding -> SMTPWSDLOperation -> input1 -> smtp:input.
3. Provide the value in property editor for message. eg: part1.

Creating the WSDL With Http Binding:

You can use the WSDL Wizard for creating the WSDL same as SMTP Binding except these changes:

    - Select Request-Response Operation in 3rd Step.
    - Select Binding Type to SOAP and Binding SubType to RPC Literal.

Creating the BPEL process:

1. Right Click on Process Files folder and select New -> BPEL Process.
2. Provide Name for the bpel process and click on Finish
3. Using the BPEl Editor / BPEL Mapper, create the bpel with these activities:
    - Receive Operation on HTTP
    - Assign the request received to the request for SMTP Invoke.
    - Invoke operation on SMTP
    - Assign a static String "Email Sent Successfully"
    - Reply Operation on HTTP.

The completed BPEL module will look like this:

Creating the Composite Application:

1. Create a new Project. Select Service Oriented Architecture -> Composite Application.

2. Provide a name for the project and click finish

3. Under the Jbi project. Right click on JBI Modules and select Add JBI Module. Find the above created BPEl project and add it.

Building and deploying the SA:

1. Right click the Comp. App. project and select Build.

2. In the Runtime tab, make sure the Application Server is started.

3. Right click the Comp. App. project and select Deploy.

Testing the application.
To Create a TestCase:

In the Comp. App. project,

1. Right Click on the Test Folder and select New Test Case
2. Provide a TestCase name and go to next screen.
3. Choose the WSDL implementing HTTP/SOAP Binding and click next.

4. Select the Operation you want to test and Click Finish

A test case would have got created with an Input.xml and output.xml. Edit the input.xml to provide the data.

Running the Test Case:

Run the Testcase by Right click on the testcase and select Run.

The First time it fails, because the output.xml is empty and it does not matches with the output returned. To make the output returned as a valid output, right click on the output returned (marked as Failed) and select "Use as Output"

Thursday Mar 08, 2007

Introducing Myself

I'm Vishnuvardhan working in Sun Microsystems, Bangalore. I'm currently involved in development of JBI based SMTP Binding component. Watch my next blog entry for a tutorial on usage of SMTP Binding component.



« July 2016