GlassFish ESB v2.2 was released in late December/early January 2010. This release brings a number of design-time improvements in handling HL7 v2 messages. Some of these have been on my and other people’s wish lists for years.
HL7 v2 structure nodes use full names, rather then acronyms like MSH.1. In BPEL, mapping can be performed at message, segment, component, subcomponent and field level.
When working on the HA solutions discussed in my HA blog ebntry I realized that it will be difficult to work out whether messages are delivered in order, as was required, and whether any are missing. I got over the issue by ensuring that my test data was prepared in such a way that messages in each test file had increasing, contiguous sequence numbers embedded in the message. For HL7 v2, which is the messaging standard with which I dealt, I used MSH-10, Message Control ID field. I wrote processed messages and acknowledgments to files whose names embedded MSH-10 Message Control Id, with the sequence number, so breaks in sequence and out of order messages could be readily detected.
With multiple message files containing between 1 and 50,000 messages, adding a sequence number to each message by hand was clearly out of the question.
I put the GlassFish ESB to use. I constructed a file-to-file BPEL module project to read each test file and to prepend a sequence number to each message’s MSH-10 field. The only snag was how to get a sequence number that would start at 0 and increase by 1 for each message, such that each BPEL process instance would get the next sequence, and that messages would be written to the output file in order.
This note discusses how I went about accomplishing the task.
In some specific circumstances, for example when testing high availability and failover scenarios, it may be desirable to make a BPEL process wait for a random amount of time, not exceeding some maximum duration, before continuing.
Every now and then there arises a need to carry out-of-band information alongside the business payload but without disturbing or modifying it. Message Envelope Pattern is the Enterprise Integration Pattern label that is typically applied to solutions that address this issue. How the issue is addressed in practice varies depending on the technology in use. For JMS, for example, JMS Message Properties could be used to carry out-of-band information while the payload would be carried as the JMS payload. Web Services, typically using SOAP over HTTP, can address this requirement through the SOAP Header Extension Mechanism, whereby custom headers can be added to the SOAP Header while the payload is carried in the SOAP Body.
This document discusses construction of a WSDL that supports custom SOAP Header element and BPEL processes that are used to set and get custom header values in JBI and in eInsight. This mechanism is known to work in Java CAPS 5.x, Java CAPS 6 Classic and OpenESB / GlassFish ESB.
It is assumed that the reader is sufficiently familiar with the GlassFish ESB / OpenESB BPEL Service Engine and the SOAP/HTTP Binding Component, and / or Java CAPS Classic eInsight Business Process Manager and eDesigner IDE to be able to build projects without a step-by-step pictorial document.
In some views SOA is represented as a series of 4 layers: Presentation Layer (SOA 1), Business Process Layer (SOA 2), Business Service Layer (SOA 3) and Technical Layer (SOA 4). Typically each layer higher up in the hierarchy consumes services exposed by the layer under it. So the Presentation Layer would consume services provided by the Business Process or Business Service Layers. Service interfaces are described using Web Services Description Language (WSDL), sheltering service consumers from details of service implementation. Web Services are seen as the technical means to implement the decoupled functional layers in a SOA development. Decoupling allows implementations of business functionality at different layers to be swapped in and out without disturbing other layers in the stack.
In this document I will implement a multi-operation Web Service that will allow patient information to be upserted into a database table and will return all patient details for a patient whose Facility+Local ID are specified in the request. This service will be used to populate the patient table and to implement patient lookup portlets, discussed in other writeups in this series. This is a basic Patient Service that hides the specifics of interaction with the patient data store form applications that need to interact with it, by providing a defined interface and web service-based implementation. Thus the data store may change but the service consumers need not. We use the Database BC with select, insert and update operations and Database BC with SQL File-based parameterized SQL prepared statement. We handle null value insertion on missing data. We also use the SOAP/HTTP BC and the BPEL SE. The business idea is that patients are looked after in various healthcare facilities. Information about patients is stored in a relational database. This information must be inserted, for new patients, and updated, for existing patients, as required. Frequently applications need to search for a patient and display details to human operators. To shelter application developers from the details of the data store the upsert functionality and patient details lookup functionality will be made available as a multi-operation web service.
“Progress” notwithstanding, Healthcare environments still extensively use the HL7 v2.x Delimited messages for conveyance of patient and patient-related information between applications. The GlassFish ESB provides support for HL7 v2.x messaging in the form of the HL7 Encoder, which allows conversion between HL7 v2 Delimited and HL7 v2 XML message formats, and in the form of the HL7 Binding Component, which allow connectivity between the GlassFish ESB-based healthcare solutions and healthcare applications that support HL7 over TCP connectivity.
In this document I will walk through the process of generating HL7 v2.3.1 delimited messages from pipe-delimited records containing patient information, sending and receiving HL7 v2.3.1 delimited messages using the HL7 Binding Component, parsing HL7 v2.3.1 delimited messages and writing HL7 v2 delimited messages to a file. To create and process HL7 messages I show how create a custom ADT A04 XML Schema and a custom “any HL7 v2 message” XML Schema. This gives me an opportunity to use the File Binding Component (File BC), the HL7 BC, the HL7 Encoder, the Custom Encoder and the BPEL Service Engine (BPEL SE). This also gives me an opportunity to demonstrate a HL7 v2.3.1 delimited message sender solution and to demonstrate a HL7 v2.3.1 delimited message receiver solution. At the end of the process we will have a file containing HL7 v2 delimited ADT A04 messages, which we will use in related writeups.
This Quick Note discusses a simple solution to the use case provided by Leonard Barkley. The question goes like this:
“I dont have any idea how to implement BPEL process but the BPEL deployed as a subscriber of a topic. usually I implement the BPEL process and deployed it as web service.”
We produce a simple GlassFish ESB v2.1-based solution which reads a file, sends its content to a JMS Topic and another simple GlassFish ESB v2.1-based solution which subscribes to the same JMS Topic, receives the message and writes it to a file. Both solutions will use BPEL to implement the simple logic, though it is possible to implement both solutions without BPEL, so we have File BC -> BPEL SE -> JMS BC -> JMS Provider (Topic) -> JMS BC -> BPEL SE -> File BC.
As Leonard Barkley pointed out to me, having implemented the sample, the Note is incorrect on Pages 23 and 24. The JMSSubscriber_JMSIn WSDL should use the Receive type, not Send type as the docuent states. The solution still works, it appears, but the configuration as documented is confusing. Thanks Leonard.
This Note walks the reader through development of a Java
CAPS 6/JBI-based / OpenESB-based solution that addresses a Healthcare-related
business problem. The Note elaborates on the healthcare background necessary to
get a notion of what is being done and why, and provides detailed steps
required to implement and exercise the solution to the business problem.
We will use the HL7 Binding Component, the File Binding
Component, the JMS Binding Component, the SOAP/HTTP Binding Component, the BPEL
2.0 Service Engine, the JavaEE Service Engine, the HL7 Encoder and EJB-based
Web Services in a JBI-based solution.
In the process we will create XML Schema Documents (XSDs),
Web Services Description Language Documents (WSDLs), a BPEL 2.0 Business
Process, an EJB-based “Implementation First” web service, an EJB- and
WSDL-based “Interface First” web service, a bunch of Composite Applications,
BPLE 2.0 mapping, BPEL 2.0-based Web Service orchestration, on-the-fly
conversion of HL7 version 2.3.1 delimited messages to their XML equivalents. We
will get a pretty good exposure to what OpenESB and Java CAPS 6/JBI components
look like, how they work and how they can be used to create real business
solutions. Above all, we will develop and test a solution that is more
sophisticated then the customary “Hello World” examples but not so complex as
to take too long to build and become too hard to comprehend by a novice user.
The particular business problem and the particular solution
came about because once upon a time there was intent to build a series of
related OpenESB projects – HL7 Processor, MDM Processor and IEP Processor -
receive HL7 v2.x delimited messages
convert HL7 v2.x messages to their equivalent XML format
split message stream into ADT A01s, ADT A03s and other
convert A01s to an abbreviated Custom Patient XML format
convert A03s to an abbreviated Custom Discharge format
send Custom Patients to a JMS Queue for processing by a MDM solution
send Custom Discharges to a JMS Queue for processing by an IEM solution
have the MDM process Custom Patients into a Master Patient Index
have the IEP process Custom Discharges to flag excessive length of stay
The MDM Processor and the IEP Processor made it to the Sun CEC
2008 as demonstrations, with associated Tutorials by Tom Barrett, and
demonstration recordings by me. The HL7 Processor did not make it. With the
appearance of Java CAPS 6 Update 1 more JBI components made it into the
officially supported Sun product. While the HL7 BC and the HL7 Encoder did not
make it into this Update they will, eventually. Both components are already
available from the OpenESB site and can be installed into the Java CAPS 6
Update 1 installation as unsupported components. This is what we will do for
Following the CEC 2008 Conference in Las Vegas, where the Java CAPS Stream saw a bunch of presentations and demonstrations, I am happy to offer screencasts of the three demonstration sessions I recorded for the event.
The GlassFish ESB screencast is the ScreenCast of the CEC 2008 GlassFish ESB Essentials Lab
demonstration. This is a
recording of the demonstration described in detail by Tom Barrett in
the GlassFish ESB Tutorial and Lab document. The screencast is an extended version of what the CEC audience got to see. In this screencast I use the OpenESB distribution to discuss, design and implement an abbreviated Supply Chain solution. I use the File BC, the SOAP/HTTP BC, BPEL 2.0 SE, the Customn Ecoder, the XSD Editor, the WSDL Editor, BPEL correlations, BPEL Pick wit Timer, CASA Editor and a bunch of other OpenESB/GlassFish ESB featiures and facilities. Watching the screencast will give you a pretty good idea what the tooling looks like, how easy it is ti use it, how a theoretical requriement can be turned into a practical design and how that design can be implemented and exercised using the tooling and infrastructure you can get free of charge and use as much as you might desire.
Data for the following two screencasts/demonstrations is produced by the solution discussed in the next blog entry, which ought to precede these two.
The Java CAPS 6/Mural Master data Management screencast is the ScreenCast of the CEC 2008 Java CAPS Essentials Master Data Management (MDM) Lab demonstration. This is a recording of the demonstration described in detail by Tom Barrett in the Java CAPS Essentials MDM Tutorial and Lab document. In the screencast I discuss what the Master Data Management (MDM) is, how a Healthcare enterprise might leverage it to improve its business and how the OpenESB or Java CAPS 6 can be used to implement MDM. I use OpenESB to design a Master Patient Index Data Model, implement it with the tool, generate Data Model-based Master Index Data Management Web Application, build an integration solution to feed the MDM solution with transactional data form Hospital Information Systems and build a broadcast processor solution that can be used to send master patient index updates to downstream systems which have a need to be kept in synch with the enterprise view of the patient. One will get a very good idea of what the core Master Data Management is about, how easy it is to create the MDM Application and related integration components using the OpenESB/Java CAPS 6 tooling, and how the business of maintaining master patient index looks and works like.
The Java CAPS 6 / Intelligent Event Processor screencast is the ScreenCast of the CEC 2008 Java
CAPS Essentials IEP Lab demonstration. This is a recording of the demonstration described in
detail by Tom Barrett in the Java CAPS Essentials IEP Tutorial and Lab
document.The screencast is what the CEC audience got to see. In this screencast I demonstrate how an Intelligent Event Processing (IEP) solution is built and exercised. The solution addresses a Helathcare business problem - it calculates an Average Length of Stay for each patient in a sliding time window, based on data from an ADT A03 HL7 Discharge message, works out which patients' Length of Stay exceeds average for the patients in the window by 1.5 times, and passes records related to these patients on while discarding 'normal' records.
The AVIs were recorded with Camtasis Studio. You may need a Camtasia Player to playe them on Windows. You could also try getting a Camtasis codec for your platform/player from the Camtasia site.
I had audio quality problems when directly playing the recordings through Mozilla, which used the Quicktime plugin. The best thing to do is to download the recordings and try different players until one works for you.;
Java CAPS 6 has the 5.x compatibility infrastructure which allows one to import 5.x projects right into Java CAPS 6, build, deploy and run without changes. One can also develop repository-based projects in Java CAPS 6 – that’s the 5.x-style projects.This is the old way of developing Java CAPS solutions – still good and valid. If one were to decide to not use the old way there is the JBI infrastructure, which allows development of solutions that use BPEL Service Engine, XSLT Service Engine, IEP Service Engine, Java EE Service Engine, etc., and a variety of Binding Components. The implication is that business logic is implemented in BPEL 2.0, which is used to orchestrate other services and resources, including interaction with external systems through Binding Components. This is the new way of developing Java CAPS solutions – 100% compatible with the Open Source OpenESB project since it uses the OpenESB project-developed container and components.
Someone might ask “so what happened to eGate?”. “eGate” meaning Java Collaboration Definition-like logic components, eWays and the JMS messaging backbone.
While the facility seems underadvertised/downplayed, Java CAPS 6 provides a number of 5.1 eWay-based JCA Adapters and a moderately easy means of developing JCA Message-Driven Beans that can use these adapters to implement JCD-like logic components and, effectively, eGate-like solutions that do not use BPEL or the JBI infrastructure.
This Note discusses and illustrates the implementation of a mixed Java CAPS 5.x-like integration solution that retrieves a file from the local file system using JCA Adapters and passes its content to a BPEL 2.0 process executing in the JBI container. This requirement I have seen and heard of being implemented in 5.x many times by many customers.
Most of the material in the first 16 pages of this Note is the same as in Note 2.
The JCA Message-Driven Bean, the piece of JCD-like Java logic, will be triggered by a Batch Inbound Adapter (what one would have called the BatchInbound eWay in 5.1), will read the content of the file using the Batch Local File Adapter (eWay) and will send the payload as a string to a BPEL 2.0 Business Process, which will be triggered by this message and will execute in the JBI container. The batch Inbound Adapter will be configured to use a regular expression to match the name of the file. Once it finds the file it will rename the file by prepending the GUID to the name and will pass the new name, the original name and the directory path to the Java code. This is exactly what the 5.1 Batch Inbound does. The JCA MDB will use the new name, the original name and the directory path to dynamically configure the Batch Local File Adapter to retrieve the file content and rename the file (post transfer) to the original name with some string appended to indicate that the file was processed. This, too, is exactly what one would do in a 5.1 JCD in the same circumstance. Once the payload is available the JCA MDB will use the OneWay WSDL interface and the JBI NMR to send it, as a String, to a BPEL 2.0 process.Both the JCA MDB and the BPEL process will be a part of the same JBI Composite Application and will communicate with one another using the Normalized Message Router (NMR).
As implemented in OpenESB and Java CAPS 6/JBI, JBI at first put me off completely. I had no idea where to start and what to do. This was particularly annoying as I was reasonably effective in developing solutions using Java CAPS 5.x and did not look forward to trying to figure out how to do in OpenESB the same thing I already new how to do.
This document is intended to save you the anxiety and help you get over the initial hurdles. It walks through the process of creation, deployment and execution of a simple File-to-File integration solution, with detailed step-by-step illustrations. The focus is the practice of using JBI components not the theory of JBI.
This document addresses the integration solution developers, not developers of Service Engines or Binding Components.
The projects use JBI components only, that’s why they are just as good for OpenESB exploration as they are for Java CAPS 6/JBI exploration.
JBI (Java Business Integration) is not discussed to any great extent. JBI artifact names are used in discussion but not elaborated upon. Explanations are provided where necessary to foster understanding of the mechanics of developing integration solutions using JBI technologies in OpenESB and Java CAPS 6/JBI.
Java CAPS 6 and OpenESB are two of a number of toolkits that implement the JBI specification (JSR 208). When I use an expression like “In JBI …” I actually mean “In JBI as implemented in Java CAPS 6 and OpenESB …”. The same things may well be implemented differently in other JBI toolkits.
Java CAPS 6 “Revenue Release” is used and shown in illustrations. OpenESB can be used instead however the appearance of components shown in illustrations may vary somewhat.
01File2File.zip contains the document that documents the example in an illustrated, step-by-step fashion.
In this Blog I post abstracts of articles / writeups / notes on various aspects of Java CAPS and SOA Suite including solutions, discussions and screencasts. The links to the referenced material are included in the bodies of the abstracts.