Sample Project Overview

The TCP/IP HL7 Adapter includes several sample projects that you can use as templates to create your own customized projects to enable communication between external systems. These projects are designed to be extended and modified for your specific project requirements. The TCP/IP Adapter includes the following sample projects:

• prjHL7Inbound

• prjHL7Outbound

• prjHL7Inbound-MLLPV2

• prjHL7Outbound-MLLPV2

• prjHL7Inbound-XML

• prjHL7Outbound-XML

• prjHL7V2toV3_AND_ebXML

• prjHL7V3CommonJcdsInbound

• prjHL7V3Inbound

• prjHL7V3Inbound_WithSchematron

• prjHL7V3Outbound

Some of these projects include a predefined Environment so you do not have to create one from scratch. This tutorial concentrates on two of the sample projects: prjHL7Inbound and prjHL7Outbound. Each of these projects demonstrate multiple operations (Collaborations), and the tutorial takes you through configuring, building, and deploying the projects. Ad additional section at the end of this tutorial goes through the prjHL7V3Inbound_WithSchematron sample to illustrate how to implement schematron validation in HL7 V3.

Standard Inbound and Outbound Samples

The first section of the tutorial deals with standard inbound and outbound sample projects, which include a variety of Collaborations and Connectivity Maps for you to deploy.

prjHL7Inbound Project

The prjHL7Inbound project includes the following Connectivity Maps, both of which use the same Collaboration:

• HL7 Inbound: A standard inbound HL7 messaging operation that receives the HL7 messages from an external system, sends an acknowledgement of the message, provides sequence numbering, writes the HL7 message to a JMS data queue, and also writes the HL7 message and ACK to a JMS Journal queue.

• HL7 Forward Message Inbound: Inbound forward message mode is used with the outbound delayed ACK. Its purpose is to get a message from an outbound forwarder and return an acknowledgement.

prjHL7Outbound Project

The prjHL7Outbound project includes the following Connectivity Maps:

• HL7 Outbound: A standard outbound HL7 messaging operation that receives the HL7 message from the JMS data queue, provides sequence numbering, sends the HL7 message to an external system, receives an acknowledgement from the external system, and writes the HL7 message and the ACK to a JMS Journal queue.

• HL7 Forward Outbound: Outbound forward message mode is used with the delayed ACK. Its purpose is to get a message from a JMS queue and send it to an external system. No validation is performed.

• HL7 Outbound Delayed ACK: Delayed Acknowledgement is similar to HL7Outbound, but the initial acknowledgement is received from the receiving system. After the sender receives the first ACK, it waits for a second ACK that indicates that the message was received by the external HL7 system.

Schematron V3 Inbound Sample

The second section of the tutorial deals with standard inbound and outbound sample projects, which include a variety of Collaborations and Connectivity Maps for you to deploy. The schematron sample illustrates how to perform schematron validations against the incoming message. Schematron validation uses the concept of finding tree patterns in the parsed document rather than the grammar, which allows representation of numerous structures that are difficult in grammar-based schema languages.

The inbound schematron project includes the following Connectivity Maps, each of which process message in different ways depending on how the Adapter is configured in the Connectivity Map and which Collaboration is in use:

• HL7 V3 Deferred Inbound

• HL7 V3 Inbound

• HL7 V3 Message Publisher

• HL7 V3 Queue Manager

Sample Project Components

The TCP/IP HL7 Adapter projects provide predefined adapter components designed to be extended and modified for your specific project requirements. Projects are created using tools in the NetBeans IDE. Use Deployment Profiles to deploy projects to specific logical hosts in specific Environments. Components developed for use in one project can be used in another, and a project can internally reference another project.

The components found in a typical project include the following:

• Services: A service provides a framework for a process or a Collaboration.

• External Applications: The Enterprise Service Bus system integrates external applications which are logical representation of external software applications. An adapter links such applications to a Service.

• Schedulers: A Scheduler allows a service to be performed at a prescribed interval.

• Component Connections: When you link two components on a Connectivity Map, NetBeans places either an adapter or JMS Client connection icon on the link, depending upon the type of components you are linking. When an External Application and a Collaboration are linked, the link contains an adapter. When a Service and a Message Destination (queue or topic) are linked, the link contains a JMS Client Connection.

• Message Destinations: A Message Destination is a container for stored data, and can follow either the topic or queue JMS model.

  • Topic: A topic is a message destination that conforms to the publish-and-subscribe messaging model (one to many).

  • Queue: A queue is a message destination that conforms to the point-to-point messaging model (one to one).

These components are graphically represented in a project's Connectivity Map. For example, the cmHL7Outbound Connectivity Map is shown below. This Connectivity Map does not contain a Scheduler or any Topics.

Sample Project Collaborations

The sample projects include multiple Collaborations for you to work with. These Collaborations are designed to work as is for HL7 compliant interfaces, and can be configured for your specific needs by configuring the External System properties. If an interface requires special functionality, the Collaboration's Java code is easily accessible for modification, much of which can be created graphically (drag and drop), using the Collaboration Editor's Business Rules Designer.

The Collaborations contain a number of OTDs that extend functionality for HL7 message handling, logging, error messaging, journaling, and sequence numbering. These include both generic HL7 OTDs for HL7 ACK/NAK generation or verification, and the Resource Adapter that communicates to the external system and offers services to the application server. The Collaboration controls messaging protocol and all business logic.

The Collaborations are designed to target one unit of work at a time, meaning the resolution of one message at a time. The basic structure of the Collaborations is a state machine implemented in a Java switch statement. The state machine keeps track of the messaging protocol so that when a Collaboration is invoked, it can retrieve the state of the connection just handed to it by the RA, and then execute proper actions based on the state machine.

At the end of each action, the state is set for the next execution of the Collaboration. There are three main states:

• To Establish: A new or reset connection needs to have an HL7 session established. If sequence numbering is used, the sequence numbers need to be negotiated.

• Messaging: This is where the exchange of messages and ACKs takes place.

• Shutdown: This is where any cleanup can happen before the connection is closed, or to close the connection.

Additional Collaborations can be added to a project to increase message flow.

The TCP/IP HL7 inbound Collaboration publishes received data as a Byte message in JMS using the sendBytes() method. However, the HL7 outbound Collaboration expects a Text message from JMS. The Adapter is not designed for the HL7 outbound Collaboration to subscribe to a JMS data queue created by the HL7 inbound Collaboration directly. HL7 inbound and outbound Collaborations are designed to communicate through an HL7 Adapter TCP/IP connection.