JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Java CAPS Adapter for TCP/IP HL7 User's Guide     Java CAPS Documentation
search filter icon
search icon

Document Information

Oracle Java CAPS Adapter for TCP/IP HL7 User's Guide

Oracle Java CAPS Adapter for TCP/IP HL7 Overview

About Oracle Java CAPS Adapter for TCP/IP HL7

TCP/IP HL7 Features

TCP/IP HL7 Adapter Components

About HL7

The TCP/IP HL7 Adapter Architecture

TCP/IP HL7 Resource Adapter

HL7 Collaborations

Generic HL7 Message Libraries

Oracle Java Composite Application Suite Functionality

Modes and Roles

Standard Mode

HL7 Adapter Sender Role

HL7 Adapter Receiver Role

Delayed ACK Mode

Inbound Functionality

Inbound Adapter Data Flow

Standard Inbound Message Mode Data Flow and Architecture

Inbound Receiver Message Mode

Message Verification

Acknowledgment Processing

Recourse Actions

Outbound Functionality

Outbound Adapter Data Flow

Outbound Standard Messaging Mode

Outbound Adapter Roles for Delayed ACK Scenarios

Outbound Delayed ACK Role

Outbound Forwarder Role

Message Verification

Acknowledgment Processing

Recourse Actions

General Functionality

Non-blocking I/O

HL7 Sequence Numbering Protocol

Failed Message Handling

Recourse Actions

Stopping the Collaboration with a Fatal Alert

TCP/IP HL7 Adapter Operation

Direction

Connection Type

Lower Layer Protocol

MLLP

HLLP

HL7 Acknowledgment Level

Journaling

Error Queues

Alerts and Monitoring

Support for HL7 Version 2.5 SFT Segments

Delayed Acknowledgements

Monitoring the HL7 Adapter

Schematron Support in the HL7 Adapter

Schematron Configuration in HL7 Adapter

API for Schematron Validation

Using the Schematron API

Obtaining the Factory Object

Obtaining the Validator Object

Performing the Validation

Adding and Configuring a TCP/IP HL7 Adapter in a Connectivity Map

Adding a TCP/IP HL7 External Application to a Connectivity Map

To Add a TCP/IP HL7 External Application

Modifying the TCP/IP HL7 Adapter Properties in the Connectivity Map

Modifying Adapter Properties in the Connectivity Map

TCP/IP HL7 V2 Adapter Inbound Connectivity Map Properties

General Inbound Settings - TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Settings -- TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Settings - Server Port Binding -- TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Settings - Client Connection Establishment -- TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Settings - Inbound Connection Management -- TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Schedules - Listener Schedule -- TCP/IP HL7 V2 Inbound Adapter

TCPIP Inbound Schedules - Service Schedule TCP/IP HL7 V2 Inbound Adapter

HL7 Acknowledgment -- TCP/IP HL7 V2 Inbound Adapter

Lower Layer Protocol -- TCP/IP HL7 V2 Inbound Adapter

Sequence Number Protocol -- TCP/IP HL7 V2 Inbound Adapter

HL7 MSH Segment -- TCP/IP HL7 V2 Inbound Adapter

HL7 SFT Segment -- TCP/IP HL7 V2 Inbound Adapter

Communication Control -- TCP/IP HL7 V2 Inbound Adapter

HL7 Recourse Action -- TCP/IP HL7 V2 Inbound Adapter

TCP/IP HL7 V2 Adapter Outbound Connectivity Map Properties

General Outbound Settings -- TCP/IP HL7 V2 Outbound Adapter

TCPIP Outbound Settings -- TCP/IP HL7 V2 Outbound Adapter

TCPIP Outbound Settings - Client Connection Establishment -- TCP/IP HL7 V2 Outbound Adapter

TCPIP Outbound Settings - Server Port Binding -- TCP/IP HL7 V2 Outbound Adapter

HL7 Acknowledgment -- TCP/IP HL7 V2 Outbound Adapter

Lower Layer Protocol -- TCP/IP HL7 V2 Outbound Adapter

Sequence Number Protocol -- TCP/IP HL7 V2 Outbound Adapter

HL7 MSH Segment -- TCP/IP HL7 V2 Outbound Adapter

HL7 SFT Segment -- TCP/IP HL7 V2 Outbound Adapter

Communication Control -- TCP/IP HL7 V2 Outbound Adapter

HL7 Recourse Action -- TCP/IP HL7 V2 Outbound Adapter

TCP/IP HL7 V3 Adapter Inbound Connectivity Map Properties

General Inbound Settings -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Settings -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Settings - Server Port Binding -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Settings - Client Connection Establishment -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Settings - Inbound Connection Management -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Schedules - Listener Schedule -- TCP/IP HL7 V3 Inbound Adapter

TCPIP Inbound Schedules - Service Schedule -- TCP/IP HL7 V3 Inbound Adapter

HL7 Acknowledgment -- TCP/IP HL7 V3 Inbound Adapter

Lower Layer Protocol -- TCP/IP HL7 V3 Inbound Adapter

Sequence Number Protocol -- TCP/IP HL7 V3 Inbound Adapter

HL7v3 Transmission Wrapper -- TCP/IP HL7 V3 Inbound Adapter

Communication Control -- TCP/IP HL7 V3 Inbound Adapter

HL7 Recourse Action -- TCP/IP HL7 V3 Inbound Adapter

Schematron Validation -- TCP/IP HL7 V3 Inbound Adapter

TCP/IP HL7 V3 Adapter Outbound Connectivity Map Properties

General Outbound Settings -- TCP/IP HL7 V3 Outbound Adapter

TCPIP Outbound Settings -- TCP/IP HL7 V3 Outbound Adapter

TCPIP Outbound Settings - Client Connection Establishment -- TCP/IP HL7 V3 Outbound Adapter

TCPIP Outbound Settings - Server Port Binding -- TCP/IP HL7 V3 Outbound Adapter

HL7 Acknowledgment -- TCP/IP HL7 V3 Outbound Adapter

Lower Layer Protocol -- TCP/IP HL7 V3 Outbound Adapter

Sequence Number Protocol -- TCP/IP HL7 V3 Outbound Adapter

HL7v3 Transmission Wrapper -- TCP/IP HL7 V3 Outbound Adapter

Communication Control -- TCP/IP HL7 V3 Outbound Adapter

HL7 Recourse Action -- TCP/IP HL7 V3 Outbound Adapter

Configuring Oracle Java CAPS Adapter for TCP/IP HL7 Environment Properties

Configuring TCP/IP HL7 Adapter Environment Properties

To Configure the Environment Properties

TCP/IP HL7 Inbound Adapter Environment Properties

HL7 Inbound Adapter - TCPIP Inbound Settings

HL7 Inbound Adapter - MDB Pool Settings

HL7 Inbound Adapter - Sequence Number Protocol

HL7 Inbound Adapter - Database Settings

TCP/IP HL7 Inbound Adapter Environment Properties

HL7 Outbound Adapter - TCPIP Outbound Settings

HL7 Outbound Adapter - Connection Pool Settings

HL7 Outbound Adapter - Sequence Number Protocol

Using the TCP/IP HL7 Predefined Templates

Prerequisites for the HL7 V3 Sample Projects

Creating a Copy of an HL7 Sample Project

To Create a Copy of a Project

Customizing Predefined Collaborations for HL7

Creating Copies of HL7 Collaborations

To Create Copies of HL7 Collaborations

Adding an HL7 Message Library to an Existing Collaboration

To Add HL7 Message Library to an Existing Collaboration

About TCP/IP HL7 V2 Collaborations

TCP/IP HL7 V2 Adapter Projects Overview

TCP/IP HL7 V2 Adapter Collaborations

Inbound HL7 V2 Collaboration Overview

Inbound HL7 V2 Collaboration - Part 1

Inbound HL7 V2 Collaboration - Part 2

Inbound HL7 V2 Collaboration - Part 3

Outbound HL7 V2 Collaboration Overview

Outbound HL7 V2 Collaboration - Part 1

Outbound HL7 V2 Collaboration - Part 2

Outbound HL7 V2 Collaboration - Part 3

HL7 V2 Outbound Test Collaboration

About TCP/IP HL7 V3 Collaborations

About HL7 V3

TCP/IP HL7 V3 Adapter Projects Overview

TCP/IP HL7 V3 Adapter Collaborations

Inbound HL7 V3 Immediate Collaboration Overview

HL7 V3 Standard Inbound Message Mode Data Flow (For Immediate Mode of ACK Process) -- Part 1

HL7 V3 Standard Inbound Message Mode Data Flow (For Immediate Mode of ACK Process) -- Part 2

Inbound HL7 V3 Deferred Collaboration Overview

HL7 V3 Standard Inbound Message Mode Data Flow (For Deferred Mode of ACK Process) -- Part 1

HL7 V3 Standard Inbound Message Mode Data Flow (For Deferred Mode of ACK Process) -- Part 2

HL7 V3 Standard Inbound Message Mode Data Flow (For Deferred Mode of ACK Process) -- Part 3

Outbound HL7 V3 Collaboration Overview

HL7 V3 Standard Outbound Message Mode Data Flow (For Immediate and Deferred Mode of ACK Process) -- Part 1

HL7 V3 Standard Outbound Message Mode Data Flow (For Immediate and Deferred Mode of ACK Process) -- Part 2

HL7 V3 Standard Outbound Message Mode Data Flow (For Immediate and Deferred Mode of ACK Process) -- Part 3

HL7 V3 Outbound Test Collaboration

MLLP V2 and the Sample Projects

Creating and Configuring the MLLP V2.0 Database

To Create and Connect to the Database

To Run the MLLP V2.0 Database Scripts

To Create the Connection Pool and JDBC Resource

Associating the MLLP Database With the Adapter

MLLP V2 Content Exchange Model

Standard Inbound HL7 V2 Collaboration Overview over MLLPV2

HL7 V2 Standard Inbound Message Mode Data Flow over MLLPV2 -- Part 1

HL7 V2 Standard Inbound Message Mode Data Flow over MLLPV2 -- Part 2

HL7 V2 Standard Inbound Message Mode Data Flow over MLLPV2 -- Part 3

About TCP/IP HL7 V2 Collaborations

This section provides an overview and description of the structure and functionality of the inbound and outbound Collaborations provided as part of the TCP/IP HL7 Adapter for V2.x.

The following topics provide information about the sample V2 Collaborations and provide instructions for copying and customizing them:

TCP/IP HL7 V2 Adapter Projects Overview

Several sample Projects are provided with the TCP/IP HL7 Adapter to illustrate different scenarios for connecting with external HL7 systems. You can download the sample Projects from the Downloads page of the Java CAPS Suite Installer.

While this section focuses on the standard inbound and outbound HL7 scenarios, you can choose from any of the following HL7 V2 samples:

TCP/IP HL7 V2 Adapter Collaborations

This section describes the inbound Collaboration (jcdHL7Inbound) and the outbound Collaboration (jcdHL7Outbound), provided within the standard sample Projects for inbound and outbound HL7 V2 messaging. These Collaborations are designed to work as is for HL7 V2 compliant interfaces, and can be configured for your specific needs using only the property configuration files. If an interface requires special functionality, the Collaboration's Java code is easily accessible for modification, much of which can be created graphically using the Collaboration Editor's Business Rules Designer.

The Collaborations contain a number of Message Libraries that extend functionality for HL7 V2 message handling, logging, error messaging, journaling, and sequence numbering. These include both generic HL7 Message Libraries 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 Collaborations control 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 both Collaborations is a state machine implemented in a Java switch statement. The state machine keeps track of the messaging protocol so when a Collaboration is invoked, it can retrieve the state of the connection just handed to it by the RA, and then execute the 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:

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


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


Inbound HL7 V2 Collaboration Overview

The inbound HL7 V2 Collaboration, jcdHL7inbound, contains Message Libraries for the HL7 Resource Adapter, JMS Data, HL7 ACK, JMS Journal, and JMS Error, as well as the Generic HL7 Event. The Collaboration works with its own internal code and the properties configuration files.

This following topics describe the business logic defined in the jcdHL7Inbound Collaboration:

Inbound HL7 V2 Collaboration - Part 1

The inbound Collaboration is triggered by an HL7 V2 message received from an external system or an outbound HL7 V2 client. The Collaboration calls the HL7 V2 user Collaboration rule by executing receive().

The receive method is the entry point to the HL7 V2 user Collaboration, with the following signature:

public void
receive(com.stc.connector.appconn.tcpip.hl7.HL7ServerApplication input, 
com.stc.connectors.jms.JMS otdJMS_DATA, 
com.stc.SeeBeyond.OTD_Library.HL7.Generic.HL7_GENERIC_EVT.GENERIC_EVT 
otdHL7_GENERIC_EVT_1, 
com.stc.SeeBeyond.OTD_Library.HL7.Generic.HL7_ACK.AC K
otdHL7_ACK_1,com.stc.connectors.jms.JMS otdJMS_JOURNAL, 
com.stc.connectors.jms.JMS otdJMS_ERROR) throws Throwable

Note - The above text has been wrapped to fit the page.


Once the message is received, the Collaboration determines whether the message needs to be validated. The HL7 V2 message is then validated making sure that the message structure is correct. Various fields in the MSH segment of the message are also validated, such as Version ID and Sending Facility. If these fields do not match the configuration, a NAK is returned.

If sequence numbering is enabled the Collaboration checks to see if the messages sequence number is valid. If the sequence number is not valid, the adapter sends a NAK.

The validated HL7 V2 message moves on to processInitialHandshake() and the sequence numbers are synchronized. The sequence number within the message is checked against the expected sequence number. If the numbers match, the Collaboration sends an ACK, if not it sends a NAK. The ACK or NAK includes information from various fields of the incoming MSH segment. The ACKs level of acknowledgement is set to A (acknowledgement is sent after the message is successfully processed) or C (acknowledgement is sent when the message is successfully received).

Figure 9 Inbound HL7 V2 Collaboration - Part 1

image:Inbound Collaboration — Part 1

Inbound HL7 V2 Collaboration - Part 2

The Collaboration receives the HL7 V2 message from the external using receiveHL7message(). If an exception occurs due to incomplete data and the adapter fails to read the data within the configured number of retries, the associated recourse action is taken. If the exception is due to no response, the associated recourse action is taken.

If no exception occurs, validateHL7Message() is called, which validates the message to determine whether to ACK or NAK the message. Other helper methods are also called to validate the HL7 V2 message.

If the HL7 V2 message does not pass validation, the Collaboration calls makeNak() and sendHL7Nak() to create and send the NAK to the external system. The HL7 V2 message, with the NAK, is archived to the error queue. If the number of consecutive NAKs sent surpasses the maximum number of retries, the associated recourse action is taken.

If the HL7 V2 message passes validation, the Collaboration calls makeAck() and sendHL7Ack() to create and send the ACK to the external.

Figure 10 Inbound HL7 V2 Collaboration - Part 2

image:Inbound HL7 V2 Collaboration - Part 2

Inbound HL7 V2 Collaboration - Part 3

After the ACK is sent, the HL7 V2 message and the ACK are journaled to the JMS queue Journal destination. If the message fails to journal, the associated recourse action is taken.

If sequence numbering is enabled, the processAckNakSequenceNumbering method calculates the next sequence number and stores the number in the sequence number file by calling the updateSequenceNumberFile method to persist the next sequence number.

Figure 11 Inbound HL7 V2 Collaboration - Part 3

image:Inbound Collaboration - Part 3

Outbound HL7 V2 Collaboration Overview

The outbound HL7 V2 Collaboration, jcdHL7Outbound, contains Message Libraries for the HL7 Resource Adapter, JMS Data, HL7 ACK, JMS Journal, and JMS Error, as well as the Generic HL7 Event. The Collaboration works with its own internal code and the properties configuration files. The outbound Collaboration assumes that it is reading valid HL7 V2 messages, so the data flow that feeds this Collaboration must ensure this.

The following topics describe the business logic defined in the jcdHL7Outbound Collaboration:

Outbound HL7 V2 Collaboration - Part 1

The Collaboration is triggered by a JMS HL7 V2 message. The Collaboration then calls the HL7 User Collaboration Rule by executing the receive method. Receive is the entry point to the HL7 User Collaboration, with the following signature,

receive (input, otdHL7eWay_1, otdJMS_JOURNAL, otdJMS_ERROR, otdHL7_ACK_1, 
otdHL7_GENERIC_EVT_1)

The incoming HL7 V2 message is then validated, making sure that the message structure is correct. Various fields of the message are also validated, such as Sending Facility, Version ID, and MSH.

If the message does not pass validation, an error occurs and the associated recourse action is applied. If the HL7 V2 message passes validation, the message moves on to processInitialHandshake() to receive a sequence number (if sequences numbering is enabled). The Collaboration takes the sequence number from the sequence numbering file and determines the next number to use. This number is then inserted into the HL7 V2 message.

Next, the message moves on to processMessage(), which calls the helper method, sendAndReceive(). The sendAndReceive method sends the HL7 message, waits for an HL7 ACK message, and processes the ACK or NAK. The validation also checks the message structure to see if the message is unmarshaled. If a valid ACK is not received, it continues to send the HL7 V2 message up to the configured number of retries, at which time an error occurs and the associated recourse action is taken. If a valid ACK is received, the message moves on to insertSequenceNumber().

If sequence numbering is enabled, the insertSequenceNumber method inserts the sequence number and calls sendHL7Message(). The sendHL7Message method sends the HL7 V2 message to the external using the HL7 adapter Message Library.

Figure 12 Outbound HL7 V2 Collaboration - Part 1

image:Outbound Collaboration — Part 1

Outbound HL7 V2 Collaboration - Part 2

The Collaboration receives the HL7 ACK or NAK from the external system using receiveHL7AckNak(). If an exception occurs due to incomplete data and the adapter fails to read the data within the configured number of retries, the associated recourse action is taken. If the exception is due to no response, the associated recourse action is taken. If no exception occurs, the ACK or NAK message moves on to isAckMessage(), which validates the message to determine whether the message is an ACK or a NAK.

Next the validateAckNak method unmarshals the message to the ACK Message Library and validates the MSH/MSA data. It also calls other helper methods such as checkSendingReceivingApplication() and checkSendingReceivingFacility() to validate the ACK message.

If the message does not pass validation it is handled as a NAK, the associated recourse action is taken, and the message is archived in the error queue.

If the message is a NAK, the associated recourse action is taken, and the message is archived in the error queue, along with the NAK message, as a JMS property.

If the message is an ACK and passes validation, the message is sent on to the journalMessage method

Figure 13 Outbound HL7 V2 Collaboration - Part 2

image:Outbound Collaboration — Part 2

Outbound HL7 V2 Collaboration - Part 3

If the ACK message passes validation, the HL7 V2 message and ACK message are sent to the JMS journal destination. If the message fails to journal, the associated recourse action is taken.

If sequence numbering is enabled, the processAckNakSequenceNumbering method calculates the next sequence number and stores the number in the sequence number file, calling updateSequenceNumberFile to persist the next sequence number.

Figure 14 Outbound HL7 V2 Collaboration - Part 3

image:Outbound Collaboration — Part 3

HL7 V2 Outbound Test Collaboration

In addition to the inbound and outbound HL7 V2 Collaborations, an outbound test Collaboration, jcdHL7OutboundTestDriver, is provided to test the HL7 V2 outbound and HL7 V2 outbound delayed ACK samples.

The jcdHL7OutboundTestDriver Collaboration simply picks up HL7 V2 messages from the File Adapter and sends the message to the JMS queue. This is used by the sample Projects to test the number of HL7 V2 messages processed per minute.