Hl7 Message Viewer For Mac

by

The HL7 acknowledgement message, or ACK, is critical to ensure that ongoing HL7 communication proceeds smoothly. The concept of an ACK is commonly used in many data networks protocols, including TCP, so you are likely familiar with it. Although conceptually simple (receiving system acknowledges receipt for specific message sent from sending system), there are a couple of nuances (enhanced mode, rate limiting) with HL7 ACK that make covering this topic worthwhile.

Features View HL7 Messages Identify HL7 messages, segments and fields by pointing at them View details such as maximum length, table number, optionality, etc. As its name suggests, SmartHL7 Message Receiveris a handy tool for receiving HL7 messages over the network. More precisely, the app has the role of listening to the local port designated for this.

The structure of an ACK message

Let's take a quick look at how an ACK message is created.

Let's say an inbound HL7 ADT (Admit, Discharge, Transfer) message came in with the following MSH (message header).

If the message was accepted and acknowledged, then the response ACK message (following original mode) will look like this:

Note the following:

  1. The source and destination systems have been switched;
  2. MSA segment contains the 'AA' value which indicates acceptance; and
  3. MSA segment also contains the ID of the original message.

Seems pretty straightforward but as you will see, the rules utilized to come up with this simple message can be pretty complicated.

The need for the ACK message

The need for acknowledgements is best understood when we know that:

  1. HL7 is designed around the concept of trigger events - i.e. someone got admitted, a lab test has to be ordered, lab test results have been received, patient has to be rescheduled etc.
  2. Healthcare IT systems are very 'specialized' - there are systems (often from different vendors) that focus just on ADT (admission, discharges and transfers), practice management (patient scheduling and billing), labs (lab orders, results capture and communication) etc.

So, if an event happens in one system (patient is admitted), then that event has to be sent to another system (e.g. labs) to communicate information such as internal patient identifiers (otherwise how will the lab know if the incoming order is for a valid patient or not, what identifier to use etc.). Note that these messages are usually unsolicited - i.e. ADT message is sent to all interested systems as soon as it happens without being asked for it. Additionally, as you can imagine, the volumes of messages being received by these systems could get large, hence there is a possibility the message could get dropped. The ACK serves as a confirmation that:

  1. the message (specified by an identifier) was received;
  2. the message is valid based on HL7 processing rules (more on this in a minute); and optionally
  3. the message data has been taken into a transient store like a processing queue or permanent store like a database (more on this in a minute as well).

Types of ACK messages and associated processing rules

As you can see, the ACK message is not like the delivery acknowledgement you get when you send an email or text message - it's not a 'I got it' message. One can specify whether original or enhanced processing rules are to be applied to the message. Based on this specification, the inbound message is processed differently and a different kind of ACK message is sent back. The ACK message and the associated processing rules are defined based on the MSH (message header) segment content (more details on the MSH segment was discussed in an earlier post).

Original mode

Original mode processing is indicated if both the 15th and 16th fields of the MSH segment of the inbound message is null or empty.

Any inbound message with an MSH segment indicating original mode processing will be validated for correct syntax and goes through a two step process:

Step 1 - Protocol validation

This is used to to assure that:

  1. the value in message type field (MSH - field #9) is one that is acceptable to the receiver i.e. an ADT^A20 message may be rejected by a billing system;
  2. the value in version ID field (MSH-12) is acceptable to the receiver i.e. if the systems expects HL7 v2.3.1 and the field says v2.6, then, in the immortal words from a famous film 'what we've got here is (a) failure to communicate';
  3. the value in processing ID (MSH-11) is appropriate for the application process handling the message.

If any of these checks fail, the protocol software will reject the message with an ACK message containing 'AR' in the acknowledgment code field (MSA-1). If it doesn't fail, it passes the message to the application.

Step 2 - Application validation

The application validation checks are:

  1. if the application processes the message successfully, it will generate the functional response message with a value of AA in acknowledgment code (MSA-1);
  2. or the application will send an error response, with a value of AE in acknowledgment code (MSA-1);
  3. if the application fails to process (reject) the message because of system uptime or other reasons and not for format or validation errors. The response message contains a value of AR in acknowledgment code (MSA-1). The message can sometimes be re-sent later but that is up to the sending system and the implementation to figure out.

Enhanced mode

Enhanced mode processing is indicated if at least one of the 15th and 16th fields of the MSH segment of the inbound message is not null. Enhanced mode requires that the receiving application take on additional responsibility namely that:

  1. the inbound message is received and stored;
  2. message passes syntax validation;
  3. the message type (ADT-A19 can be processed), version is correct (HL7 v2.3.1 and not v2.6 for example) and processing ID is correct - if not a commit reject (CR) message will be sent.

Based on these rules, the receiving system will send

  1. a commit accept (CA) if all OK;
  2. a commit reject (CR) as above; or
  3. a commit error (CE) for any other error.

Custom ACK

What is health IT without some customization? Not surprisingly, it is possible to send a Non-HL7/Static String ACK. This is a custom acknowledgement and is simply a text string (rather than an HL7-formatted ACK). These types of ACKs are used when an inbound system is incapable of receiving HL7 formatted messages or creating them.

Rate limiting with ACK messages

The HL7 standard defines that the sending systems cannot send another message to a system until it has received an ACK in response. Actually, that is not quite correct (thanks for a reader for pointing this out to us). It is not part of the HL7 specification. It is usually the way the HL7 systems are implemented in practice to ensure messages are handled appropriatelt. This was done, one presumes, to ensure that if messages are rejected due to errors in content, message formats, system downtime etc., they can be corrected either at the source or queued until the destination system comes back up. But as you can immediately see, if the next message won't be sent until an ACK is received, it is possible to slow down the rate of inbound messages by delaying the sending of the ACK message. Since processing of HL7 messages using open source tools have challenges when inbound message rates become high, this is one of the levers that is available to implementers to ensure messages are received and processed appropriately.

Our resident expert on HL7, Mark Olschesky explains this more as follows. Previous to v2.7, the only ACKs that were 'official' were your classic Original Mode and Enhanced Mode ACKs. There was no way that an upstream system to really know within the standard what you were going to do with the message. As such, the only valid assumption was that

  • the message was processed without error upon receiving the ACK or
  • was not processed correctly with a NACK or no ACK.

This also makes sense logistically as well, i.e. it would be dangerous to send/process an update to a patient record if you weren't able to process the initial event which would seed that patient into your system (or receive an update to a note you didn't have, etc.). Most of HL7's design is linear, and doesn't have much of a concept of eventual consistency. Note that there were always exceptions around this (notably systems which had no capability to respond with an ACK).

In 2.7, a new field was added to the 15th segment of the MSH segment of the ACK which allows the receiving system to indicate to the sending what it was going to do with the message after it received it. While folks had been doing this tacitly for years beforehand, the intent in design was to accommodate for interface engines which receive a message and then fan it out to a multitude of systems, providing some closure to the sending system as the receiving system cranked along and did its work. This was usually a tacit admonishment in design that the interface engine (and team working on it) was now responsible for troubleshooting vs. the ADT or EHR system which generated the original message type.

Now you know as much as I do about ACKs. Go forth and prosper.

If you’re looking to integrate EHR data with your application without becoming an HL7 expert, Datica can help. Learn more about Datica Compliant Managed Integration Services for HL7 here.

The topics listed here provide information about the TCP/IPHL7 Adapter sample projects that are installed automatically as partof the TCP/IP HL7 Adapter.

What You Need to Know

These topics provide information you should know about the TCP/IPHL7 sample projects.

What You Need to Do for the StandardInbound and Outbound Sample Project

These topics provide instructions to complete a TCP/IP HL7 Adaptersample project and demonstrate how a TCP/IP HL7 Adapter is implemented.

What You Need to Do for the SchematronSample Project

These topics provide instructions to complete the TCP/IP HL7Adapter sample schematron validation project.

The TCP/IP HL7 Adapter includes several sample projects thatyou can use as templates to create your own customized projects toenable communication between external systems. These projects aredesigned 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 youdo not have to create one from scratch. This tutorial concentrateson two of the sample projects: prjHL7Inbound and prjHL7Outbound. Each of these projects demonstrate multipleoperations (Collaborations), and the tutorial takes you through configuring,building, and deploying the projects. Ad additional section at theend of this tutorial goes through the prjHL7V3Inbound_WithSchematron sample to illustrate how to implement schematron validationin HL7 V3.

Standard Inbound and Outbound Samples

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

prjHL7Inbound Project

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

  • HL7 Inbound: Astandard inbound HL7 messaging operation that receives the HL7 messagesfrom an external system, sends an acknowledgement of the message,provides sequence numbering, writes the HL7 message to a JMS dataqueue, and also writes the HL7 message and ACK to a JMS Journal queue.

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

prjHL7Outbound Project

The prjHL7Outbound project includes thefollowing Connectivity Maps:

  • HL7 Outbound: Astandard outbound HL7 messaging operation that receives the HL7 messagefrom the JMS data queue, provides sequence numbering, sends the HL7message to an external system, receives an acknowledgement from theexternal system, and writes the HL7 message and the ACK to a JMS Journalqueue.

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

  • HL7 Outbound Delayed ACK: DelayedAcknowledgement is similar to HL7Outbound, but the initial acknowledgementis received from the receiving system. After the sender receives thefirst ACK, it waits for a second ACK that indicates that the messagewas received by the external HL7 system.

Schematron V3 Inbound Sample

The second section of the tutorial deals with standard inboundand outbound sample projects, which include a variety of Collaborationsand Connectivity Maps for you to deploy. The schematron sample illustrateshow to perform schematron validations against the incoming message.Schematron validation uses the concept of finding tree patterns inthe parsed document rather than the grammar, which allows representationof numerous structures that are difficult in grammar-based schemalanguages.

The inbound schematron project includes the following ConnectivityMaps, each of which process message in different ways depending onhow the Adapter is configured in the Connectivity Map and which Collaborationis 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 componentsdesigned to be extended and modified for your specific project requirements.Projects are created using tools in the NetBeans IDE. Use DeploymentProfiles to deploy projects to specific logical hosts in specificEnvironments. Components developed for use in one project can be usedin another, and a project can internally reference another project.

The components found in a typical project include the following:

  • Services: A serviceprovides a framework for a process or a Collaboration.

  • External Applications: TheEnterprise Service Bus system integrates external applications whichare logical representation of external software applications. An adapterlinks such applications to a Service.

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

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

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

    • Topic: A topicis a message destination that conforms to the publish-and-subscribemessaging model (one to many).

    • Queue: A queueis a message destination that conforms to the point-to-point messagingmodel (one to one).

These components are graphically represented in a project'sConnectivity Map. For example, the cmHL7Outbound Connectivity Mapis shown below. This Connectivity Map does not contain a Scheduleror any Topics.

Sample Project Collaborations

The sample projects include multiple Collaborations for youto work with. These Collaborations are designed to work as is forHL7 compliant interfaces, and can be configured for your specificneeds by configuring the External System properties. If an interfacerequires special functionality, the Collaboration's Java code is easilyaccessible 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 functionalityfor HL7 message handling, logging, error messaging, journaling, andsequence numbering. These include both generic HL7 OTDs for HL7 ACK/NAKgeneration or verification, and the Resource Adapter that communicatesto 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 ata time, meaning the resolution of one message at a time. The basicstructure of the Collaborations is a state machine implemented ina Java switch statement. The state machine keeps track of the messagingprotocol so that when a Collaboration is invoked, it can retrievethe state of the connection just handed to it by the RA, and thenexecute proper actions based on the state machine.

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

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

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

  • Shutdown: Thisis where any cleanup can happen before the connection is closed, orto close the connection.

Additional Collaborations can be added to a project to increasemessage flow.

Note –

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

The following topics provide information about the process coveredand this tutorial and the purpose of the sample projects:

Tutorial Process

This tutorial shows you how to work with the standard inboundand outbound sample projects that are provided with the TCP/HL7 Adapter.It also include information on working with the schematron inboundsample.

The tutorial process is divided into the following steps.

  1. Install the TCP/IP Adapter, if it is not already installed,and download the sample files.

  2. Import the projects into the Repository.

  3. Check Out the imported project.

  4. Configure the Connectivity Maps.

  5. Create and configure the Environments.

  6. Create the Deployment Profile.

  7. Build the project.

  8. Start the GlassFish server, which allows you to deployand manage projects.

Tutorial Context

In a typical real-world situation, you have an application withaccess to patient information that is periodically updated (for instance,when a patient is discharged or a lab result is issued). On the otherhand, you have parties who are interested in knowing when that informationchanges. The parties with whom you want to communicate, however, haveno direct access to the data, especially to the manner in which theapplication internally structures the data. Instead, it is likelythat other parties have their own customized methods of handling datainternally. To communicate the data to them, you need to encode itin an HL7 message, which is a widely used standard for transmittinghealthcare-related information. As long as the parties can handleHL7 messages, you can communicate your data to them.

For the purposes of this tutorial, the structure of the datainside your application bears little relation to the format of thedata specified by the HL7 standard. What is needed is an interfacebetween the application and the HL7 message, a way to efficientlyand reliably map the desired information out of the application'sdata structures and into an HL7 message, which can then be sent tointerested parties. The Java CAPS provides a flexible and intuitivemeans of designing HL7 messages and mapping the desired data intothe messages, thus making the data available to the recipient in astandard format.

To create a TCP/IP HL7 Adapter sample project, perform the followingsteps in the order given:

Installing the TCP/IP HL7 Adapterand Sample Projects

The TCP/IP HL7 Adapter is not installed by default with a standardJava CAPS installation; you need to install the Adapter manually.The Adapter is installed with the base HL7 OTD Library files and withV2.6. You can install additional HL7 OTD Library versions if needed.After install the TCP/IP HL7 Adapter to the Repository, the sampleprojects are available to download.

The Java Composite Application Platform Suite Installer is aweb-based application, used to select and upload adapters and add-onfiles to install. The Suite Installer serves as an Update Center,Management Center, and Dashboard to gain access to available applications.

Installing the TCP/IP HL7 Adapter

If you have already installed the TCP/IP HL7 Adapter using theSuite Installer but have not installed the Adapter in NetBeans, skipto Installing the TCP/IP Adapter in the NetBeans IDE. If you have installed the Adapter in both the Repositoryand NetBeans, skip to Downloading the Sample Projects.

To Install the TCP/IP HL7 Adapter

Before You Begin

Java CAPS must be installed before starting this procedure.

  1. Start the Java CAPS Repository.

    The start_repository executable file is located in your Java CAPS home directory.

  2. Open a web browser and type the following URL to accessthe Suite Installer:

    http://localhost:port_number

    where localhost is the TCP/IP host name of the Repository server andnot the name of the Repository itself, and port_number isthe port number you specified during installation for the Repository.

    The Login page of the Suite Installer appears.

  3. Enter the username and password, and then click Login.

    Note –

    The default username is admin andthe default password is adminadmin.

    The Java Composite Application Platform Suite Uploader pageappears.

  4. On the Administration Page, click to Install AdditionalProducts.

    The Welcome to the Java Composite Application Platform SuiteUploader page appears.

  5. Expand eWay under the Product Name column, and then selectHL7eWay.

  6. If you are using a version of HL7 other than V2.6, expandOTD and select HL7OTDLibrary along with the HL7 libraries for theversion you are using.

    Note –

    Note that there are several items to select to installthe full V3 HL7 Library.

  7. Click Next in the top-right or bottom-right corner ofthe page.

    The Selecting Files to Install page appears.

  8. Click Browse, and then navigate to and select the SARfile for the listed product. Click Next.

  9. Repeat the above steps for each product to install.

    Note –

    Based on your previous selection, some dependent productsmay have been added to the list.

    When you click Next after the last SAR file is selected, theInstallation Status page appears, displaying the status of the installation.The lower portion of the page displays additional information aboutthe installation process. Once a product is installed, a check markappears next to it. This might take several minutes.

    Whenthe installation is complete, the following confirmation message appears: Installation finished.

Installing the TCP/IP Adapter in the NetBeansIDE

After you install the TCP/IP Adapter in the Repository, therelated plug-ins can be installed in NetBeans. This allow you to incorporatethe Adapter into your Repository-based projects.

To Install the TCP/IP Adapter in the NetBeansIDE

  1. Start NetBeans from the Java CAPS home directory.

  2. In NetBeans, connect to the Repository (Tools menu > CAPSRepository > Connect).

  3. From the NetBeans IDE menu bar choose Tools and then Plugins.

  4. On the Plugins window, click the Settings tab.

  5. In the Configuration of Update Centers panel, select CAPSRepository Update Center and deselect all other options.

    IfCAPS Repository Update Center does not appear in the list, do thefollowing:

    1. On the Settings page, click Add.

      The UpdateCenter Customizer dialog box appears.

    2. In the Name field, enter CAPS Repository UpdateCenter.

    3. In the URL field, enter the following:

      http://HostName:PortNo/repository/RepName/data/files/InstallManager/catalog.xml

      where HostName is the name of theRepository server (or localhost), PortNo isthe Repository base port number, and RepName isthe name of the Repository.

    4. Click OK.

    Tip –

    You might need to click Reload Catalog on the Installedtab in order to see the available Java CAPS plug-ins.

  6. Click the Available Plugins tab.

    The TCP/IPHL7 components appear in the list.

  7. Select the individual components to install, or right-clickin the list and select Check All.

  8. Click Install.

  9. On the NetBeans IDE Installer, click Next, accept thelicense, and click Install.

    Note –

    Ignore any validation or unsigned warnings and continuewith the installation.

  10. When the installation completes, click Finish.

    TheIDE will restart to complete the installation.

Downloading the Sample Projects

The following instructions provide the steps to download theEnterprise Manager from the Suite Installer.

Note –

Hl7 Message Types

Before beginning this procedure, make sure the Repositoryis running for the Suite Installer.

To Download Files From the Repository

  1. On the Suite Installer, click the Downloads tab.

    A list of components ready to be downloaded appears.

  2. For the purposes of this tutorial, select HL7 AdapterInbound Collaboration Project.

  3. Save the prjHL7Inbound.zip file toa local directory.

  4. Repeat the previous step for HL7 Adapter Outbound CollaborationProject.

  5. If you want to work with the schematron validation Projectsfor HL7 V3, download HL7 Adapter Inbound Collaboration Project forHL7V3 PRPA_IN403001UV01 With Schematron Validation Enabled.

    Note –

    In order to import the V3 projects, you must have theHL7 V3 Libraries installed.

Importing the Sample TCP/IP HL7 Adapter Projects

Before you can begin working with the sample projects, you needto import them into the NetBeans IDE. For this tutorial, you needto import two projects: prjHL7Inbound and prjHL7Outbound.

Do the following to import the sample projects and make themavailable for editing:

Importing the TCP/IP Adapter Sample Projects

This section describes how to import the standard inbound andoutbound samples for HL7 V2.x.

To Import TCP/IP HL7 Adapter Sample Projects

Before You Begin

In order to import the TCP/IP HL7 Adapter sample projects, theAdapter needs to be installed and the sample projects downloaded.For more information, see Installing the TCP/IP HL7 Adapter and Sample Projects.

  1. On the NetBeans IDE, save all unsaved work.

  2. On the NetBeans menu bar, select Tools, point to CAPSRepository, and then select Import Project from the drop-down menu.

    A confirmation dialog box appears asking if you need to saveany changes.

  3. Click Yes to proceed with importing a project.

    TheImport Manager appears.

  4. Click Browse, navigate to the location of the projectZIP files, and select prjHL7Inbound.zip.

    Note –

    The associated top-level project is opened in the projectswindow after the import if you select the Open at Import check box.

  5. Click Import.

    Note –

    A warning message appears if you already have a projectof the same name in the CAPS Repository. Determine whether you wantto overwrite the existing project. In some cases the imported filewill add files to an existing project. If you do not want to overwritethe existing project, cancel the import and exit the Import Manager.Rename and save the existing project, and attempt the import again.

    It may take a few seconds to import the project. When the projectis imported, the Import Status dialog box appears.

  6. Click OK on the dialog box.

    The CAPS Repositoryis refreshed.

  7. Repeat the above steps on the Import Manager to import prjHL7Outbound.zip.

  8. Close the Import Manager.

    You should now havetwo new projects, prjHL7Inbound and prjHL7Outbound, in the tree structureof the projects window, as shown below.

Checking Out the Imported Projects

After you import a project and the Repository refreshes, theproject and all of its components are check into version control,which means they can only be viewed and not edited. You need to checkthe project out to edit the components.

To Check Out the Imported Projects

  1. On the Projects window, right-click prjHL7Inbound, pointto Version Control, and then select Check Out.

    The VersionControl - Check Out dialog box appears.

  2. Select Recurse Project to ensure all components of theprjHL7Inbound are listed.

    Note –

    You can select either one or more components.

  3. Click Select All and then click Check Out.

    Thischecks out all components of the project so you can edit them as needed.

  4. Repeat the above steps for prjHL7Outbound.

Creating and Configuring the Environments

Environments include External Systems, Logical Hosts, applicationservers, and message servers used by a project. These contain theconfiguration information for these components. Environments are createdusing NetBeans and the Environment Editor. This section describeshow to create and configure Environments for all five of the ConnectivityMaps included in the inbound and outbound projects. You only needto create Environments for the operations you want to run.

The instructions are divided into the following sections:

Creating and Configuring the HL7 OutboundEnvironment

The components required for the HL7 outbound Environment includea Logical Host, application server, JMS IQ Manager, and two externalsystems.

To Create an Environment for the prjHL7Outbound

  1. On the NetBeans Services window, right–click CAPSEnvironment and then select New Environment.

    A new environmentis created and is added to the CAPS Environment tree.

  2. Rename the new Environment to envHL7Outbound.

  3. Right-click envHL7Outbound, point to New, and then selectLogical Host.

    It takes few seconds to process the LogicalHost into the Environment.

  4. Rename the Logical Host lhHL7Outbound

  5. Create and configure an application server:

    1. Right-click lhHL7Outbound, point to New, and then selectSun Java System Application Server.

      A new applicationserver is added to the Environment tree .

    2. Rename the server gfHL7Outbound.

    3. Right-click gfHL7Outbound and select Properties.

      The Properties Editor appears.

    4. Click the ellipses button next to the Password property.

      The Password Settings dialog box appears.

    5. Click the ellipses available at the end of the field.

      The Password Settings dialog box appears.

    6. Enter the password in the Password and the Confirm Passwordfields.

      The default Password is adminadmin andthe default Confirm Password is adminadmin.

    7. Click OK.

    8. On the Properties Editor, verify the remaining propertiesand then click OK.

  6. Create and configure a JMS IQ Manager:

    1. Right-click lhHL7Outbound, point to New, and then selectSun JMS IQ Manager.

      A new JMS IQ Manager is added to theEnvironment tree.

    2. Rename the IQ Manager iqHL7Outbound.

    3. Right-click iqHL7Outbound, and select Properties.

      The Properties Editor appears.

    4. In the Sun JMS IQ Manager URL property, enter the URLof the IQ Manager.

      The default URL is stcms://localhost:18007.

    5. Enter a password as described for the application serverabove.

    6. Verify the remaining fields, and then click OK.

  7. Create and configure a File External System:

    1. Right-click envHL7Outbound, point to New, and then selectFile External System.

    2. On the dialog box that appears, enter esFile asthe name.

    3. Click OK.

      The external system is added to the Environment tree.

    4. Right-click esFile and select Properties.

      TheProperties Editor appears.

    5. On the Properties Editor, expand Inbound File eWay, andmodify the directory from which the File Adapter will pick up theinput file.

    6. Click OK.

  8. Create and Configure an HL7 External System:

    1. Right-click envHL7Outbound, point to New, and then selectHL7 External System.

    2. On the dialog box that appears, enter esHL7 asthe name.

    3. Click OK.

      The External System is added tothe Environment tree.

    4. Right-click eHL7 and select Properties.

      TheProperties Editor appears.

    5. On the Properties Editor, expand HL7 Outbound eWay, andselect TCPIP Outbound Settings.

    6. Make sure the hostname and port are correct for the applicationthat is listening for HL7 messages.

    7. Click OK.

  9. On the NetBeans toolbar, click Save All.

Creating Environments for the HL7 Inboundand Outbound Samples

Follow the example given in the previous section, create Environmentsfor the remaining TCP/IP HL7 samples. You only need to create Environmentsfor the samples you want to run. Make sure the configure the URL andauthentication information for all the application servers and JMSIQ Managers you add. Any additional required configuration is listedbelow.

Tip –

Even if you do not modify the Environment components ofan External System, be sure to open the Properties Editor for eachExternal System. Otherwise, the build process may fail.

HL7 Inbound Sample

Create the envHL7Inbound Environment with the following components:

  • HL7 External System

  • Logical Host

    • GlassFish (Sun Java System Application) Server

    • Sun JMS IQ Manager

HL7 Inbound Forward MSG Sample

Create the envHL7InboundForwardMSG Environment with the followingcomponents:

Hl7

  • HL7 External System

  • Logical Host

    • GlassFish (Sun Java System Application) Server

    • Sun JMS IQ Manager

HL7 Outbound Delayed ACK Sample

Create the envHL7OutboundDelayedACK Environment with the followingcomponents:

  • HL7 External System

    Configure the HL7Outbound eWay > TCPIP Outbound Settings properties.

  • File External System

    Configure the InboundFile eWay > Parameter Settings properties.

  • Logical Host

    • GlassFish (Sun Java System Application) Server

    • Sun JMS IQ Manager

HL7 Outbound Forward Sample

Create the envHL7OutboundForward Environment with the followingcomponents:

  • HL7 External System

    Configure the HL7Outbound eWay > TCPIP Outbound Settings properties.

  • Logical Host

    • GlassFish (Sun Java System Application) Server

    • Sun JMS IQ Manager

Configuring the Connectivity Map Properties

For certain sample projects, the Connectivity Maps do not needto be configured. For Connectivity Maps that include the File Adapter,the name of the input files needs to be configured. If you are runningthe HL7 outbound or the HL7 outbound delayed ACK sample, perform thetask below.

To Configure the Connectivity Map Properties

  1. On the Projects window, expand prjHL7Outbound.

  2. Open either cmHL7Outbound or cmHL7OutboundDelayedAck inthe Connectivity Map Editor.

  3. Double-click the Adapter icon on the line connecting theFile External System to the Service.

    The Properties Editorappears.

  4. In the Input File Name field, enter the name or the namepattern for the input file.

  5. Click OK.

Creating the Deployment Profile

A Deployment Profile is used to assign the connectivity componentsto the Environment components, including the application server andmessage server. You only need to create a Deployment Profile for thesample projects that you will run. The following procedure describeshow to create a Deployment Profile for the HL7 outbound sample. ConnectivityMap and Environment combinations for the other samples are listedat the end of this procedure.

To Create the Deployment Profile

  1. On the Projects window, right-click prjHL7Outbound Project,point to New, and then select Deployment Profile.

    TheCreate Deployment Profile dialog box appears.

  2. For the Deployment Profile Name, enter dpHL7Outbound.

  3. For the Environment, select envHL7Outbound.

  4. For the Connectivity Map, select cmHL7Outbound and deselectall other Connectivity Maps.

  5. Click OK.

    The Deployment Editor appears.

  6. Click Automap.

  7. On the Automap confirmation dialog box, click Close.

    The tree structure of the mapped Environment appears, as shown.below

  8. Save the Deployment Profile.

Creating Deployment Profiles for the HL7Inbound and Outbound Samples

Create Deployment Profiles for the remaining TCP/IP HL7 samplesfollowing the procedure above and using the following combinationsof Environments and Connectivity Maps.

HL7Inbound Inbound Sample

Use the following to create the dpHL7Inbound Deployment Profile:

  • Environment: envHL7Inbound

  • Connectivity Map:cmHL7Inbound

HL7Inbound ForwardMSG Sample

Use the following to create the dpHL7InboundForwardMSG DeploymentProfile:

  • Environment: envHL7InboundForwardMSG

  • Connectivity Map:cmHL7InboundForwardMSG

Hl7

HL7Outbound OutboundDelayedACK Sample

Use the following to create the dpOutboundDelayedACK DeploymentProfile:

  • Environment: envOutboundDelayedACK

  • Connectivity Map:cmOutboundDelayedACK

HL7Outbound Forward Sample

Use the following to create the dpHL7OutboundForward DeploymentProfile:

  • Environment: envHL7OutboundForward

  • Connectivity Map:cmHL7OutboundForward

Building and Deploying the Project

The Build process compiles and validates the project's Javafiles and creates a project enterprise application archives (EAR)file. This file runs on an application server. Deploying the projectsdeploys the EAR file to the application server.

Perform the following steps for each of the Deployment Profilesyou want to deploy:

Starting the GlassFish Server

The deployment will fail if the application server is not started.

To Start the GlassFish Server

Before you can deploy a project, you need to start the applicationserver.

  1. On the Services window, expand Servers.

  2. Right-click GlassFish V2 and select Start.

    TheGlassFish server starts. This may take a few minutes

Building a Project

Once the Deployment Profile is created and the ConnectivityMap and Environment components are mapped, you can build the project.This creates the EAR file that gets deployed to the application server.

To Build a Project

  1. Open the Deployment Profile you want to build.

  2. Click the Build icon on the Deployment Editor toolbar.

    Note –

    If the build fails, an error dialog box appears and theerrors are listed in the Validation window. Correct any errors andrebuild. Validation errors will occur if you did not open the ExternalSystem Properties Editors in the Environment.

  3. When the build is complete, a confirmation dialog appears.Click OK to close it.

Deploying the Project

Once you deploy the project, it will immediately begin running.If there are any input files in the specified input directory, theywill be processed.

To Deploy the Project

  1. On the Deployment Editor toolbar, click Deploy.

    A message appears in the lower left side of the window whenthe project is successfully deployed.

Running the Samples

The inbound and outbound TCP/IP HL7 sample projects demonstrateseveral different operations. Only deploy the Connectivity Maps thatcontain the scenario you want to run. For the outbound projects thatuse a File Adapter, use the following procedure to run data in. Forthe other projects, you will need an HL7 simulator or HL7 applicationto send and receive messages.

To Run a Sample Project

Before You Begin

Make sure the Connectivity Map you want to run is deployed.

  1. Create a text file with the following content. Name thefile HL7Msg1.txt (unless you modified the filename in the Connectivity Map properties).


  2. Place the sample input file in the configured input directoryfor the File Adapter.

    When the File Adapter picks up thefile, it appends “.~in” to the filename.

  3. Verify the output data from your output directory.

    This sample contains messages that the recipient will acceptas valid and properly formatted. The sample messages are used to designthe interface.

    HL7 Messages are ASCII messages (unlike protocols such as DICOM),and the standard requires that they be human readable.

Monitoring the HL7 Adapters

You can monitor a running HL7 Adapter on the Enterprise Manager.In order to do this, you need to have the HL7 Adapter plug-in installedon the Enterprise Manager. See Installing Additional Componentsfor Java CAPS 6 for more information.

Note –

For the outbound adapter, monitoring is performed periodicallybased on a time period defined in the HL7 Adapter web applicationsdeployment descriptor, web.xml/

To Monitor the HL7 Adapters

  1. Start the Enterprise Manager.

    Tip –

    You can use the start_emanager shortcutin the Java CAPS home directory.

  2. Open a web browser and log in to the Enterprise Managerusing the following URL:

    http://host-name:port-number

    where host-name is the name of theserver on which Enterprise Manager is installed, and port-number is the Enterprise Manager port number (15000 by default).

  3. In the left pane of the Enterprise Manager expand JavaEE > prjHL7Inbound > Deployment1 > cmHL7Inbound, and then select eaHL7Inbound.

    A new frame appears with a list of actions under a nodenamed eaHL7Inbound => jcdHL7inbound1.

  4. Execute the sample project using an HL7 simulator.

  5. Under eaHL7Inbound => jcdHL7inbound1, select Logging toview log messages.

  6. Select Alerts to view alerts and their statuses.

  7. Select Monitor External Connection to view informationabout the connection to the external system.

    This actiondisplays the screen as shown below.

  8. Terminate the external system and observe that the statusinformation of the terminated system no longer appears in the statustable

This sample project receives an HL7 V3 message, PRPA_IN403001UV01,and sends an HL7 V3 ACK or NAK, MCCI_IN000004UV01. This project issame as prjHL7V3Inbound except for the schematron validation for theinput XML.

Follow these steps in the order given to complete the schematronsample:

Importing the Sample Project

In order to work with the sample project, you need to downloadit from the Repository using the Suite Uploader and then import itusing NetBeans.

To Import the Sample Project

Before You Begin

Make sure the required Message Libraries are installed. In additionto the HL7 OTD Library and HL7 OTD Generic Library, which are installedwith the TCP/IP HL7 Adapter by default, you need to install the followingtwo libraries:

  • HL7V32006PatientAdmin.sar

  • HL7V32006TransInfra.sar

  1. If the TCP/IP HL7 Adapter is not already installed, installit now as described in Installing the TCP/IP HL7 Adapter and Installing the TCP/IP Adapter in the NetBeans IDE.

  2. Download the schematron sample project and the HL7 V3outbound project, as described in Downloading the Sample Projects.

  3. Import the project file.

    1. On the NetBeans IDE, save all unsaved work.

    2. On the NetBeans menu bar, select Tools, point to CAPSRepository, and then select Import Project from the drop-down menu.

      A confirmation dialog box appears asking if you need to saveany changes.

    3. Click Yes to proceed.

      The Import Manager appears.

    4. Click Browse, navigate to the location of the projectZIP files, and select prjHL7Inbound_WithSchematron.zip.

    5. Click Import.

      Note –

      A warning message appears if you already have a projectof the same name in the CAPS Repository. Determine whether you wantto overwrite the existing project. In some cases the imported filewill add files to an existing project. If you do not want to overwritethe existing project, cancel the import and exit the Import Manager.Rename and save the existing project, and attempt the import again.

      It may take a few seconds to import the project. When the projectis imported, the Import Status dialog box appears.

    6. Click OK on the dialog box.

      The CAPS Repositoryis refreshed.

    7. Close the Import Manager.

      You should now havetwo new projects in the tree structure of the Projects window.

    Note –

    In the current example, the JAR file (checkprofileid.jar) is bundled along with the sample project file importedfrom Java CAPS Repository, prjHL7V3Inbound_WithSchematron.

Hl7 Message Viewer For Mac Os

Checking Out the Project

When you first import a project, all of its components are checkedin to version control. This means you cannot edit the project. Youneed to check the components out first.

To Check Out the Project

  1. In the NetBeans Projects window, right–click prjHL7V3Inbound_WithSchematron.

  2. Point to Version Control, and then select Check Out.

  3. On the Version Control dialog box, click Recurse Project,and then click Select All.

  4. Click Check Out.

Modifying the Connectivity Map

To Modify the Connectivity Map

  1. On the NetBeans Projects window, double-click cmHL7V3Inbound.

    The Connectivity Map appears in the Connectivity MapEditor.

  2. Double-click the Adapter icon on the connecting line betweenthe eaHL7V3Inbound External System and the jcdHL7V3Inbound1 service.

    The Properties Editor appears.

  3. Select Schematron Validation in the left panel.

  4. Modify the properties as follows:

    • Enable Schematron Validation:true

    • Schematron Files:Provide a list of Schematron files. Use a comma to separate multiplefiles.

Modifying the Java Collaboration Definition

The JCD is edited as described in the steps below.

Modify the Collaboration Editor

  1. In the NetBeans Projects window, double-click jcdHL7V3Inbound.

    The Collaboration appears in the Java Collaboration Editor.

  2. Modify the Collaboration rules as needed.

    Thefollowing sections describe parts of the JCD that define schematronvalidation.

Schematron Validation Inside the JCD

The schematron validation API is invoked from the JCD. The JCDfollows the standard HL7 V3 validation; the schematron validationAPI is only invoked if the Enable Schematron Validation property istrue. Following is an excerpt from the JCD code that scans the schematronfiles list and calls the method validateWithSchematron() if schematron validation is enabled.

Excerpt for Beginning Schematron Validation


The above text has been wrapped for display purposes. The imagesbelow show the code as it appears in the Collaboration Editor.

validateWithSchematron() method

The schematron method invokes the schematron API. It reads theschematron files from classpath and constructs a DOM source. The DOMsource passes it to obtain the SchematronValidator object.The object invokes the validate() methodto pass the hl7payload. The following excerpt from the JCD definesthe validation method.


The above text has been wrapped for display purposes. The imagesbelow show the code as it appears in the Collaboration Editor.

Retrieving the Validation Results

The makeNAK() method retrieves theXML document generated from the schematron validation. The XML documentis embedded in the AcknowledgementDetail section of HL7V3 AcknowledgementXML. The following excerpt defines the makeNAK() method.

makeNAK() method


The above text has been wrapped for display purposes. The imagebelow shows the code as it appears in the Collaboration Editor.

Creating and Importing Sample Files

This section provides sample schematron validation and inputfiles, and also gives instructions on importing the validation filefor use in the JCD.

Sample Schematron

Below is a sample schematron validation file that checks forthe presence of the profileid field in the PRPA_IN403001UV01OTD.


Sample Input Document


Note –

The above text has been wrapped for display purposes.It contains extra line breaks.

Hl7 Message Viewer For Macbook

Importing a Schematron XML File

This tutorial includes a JAR file, checkprofileid.jar.which includes the sample schematron validation file described above.Follow this procedure if you want to create your own validation fileand package it for the JCD.

To Import a Schematron XML and Add it to theJCD

  1. Create a JAR file containing the schematron validationfile in XML format.

  2. Do the following to import the JAR file:

    1. Right-click the schematron project, point to Import, andthen select File.

    2. Navigate to and select the JAR file.

    3. Click Select, and then click Import.

      The filenow appears in the Projects window beneath the schematron project.

  3. Open the Collaboration in the Collaboration Editor.

  4. On the Collaboration Editor toolbar, click Add JAR.

  5. On the Add/Remove Jar Files dialog box, click Add.

  6. Navigate to and select he JAR file to add, and then clickImport.

  7. On the Add/Remove Jar Files dialog box, click Close.

Creating the Environment

Follow the steps below to create an Environment for the cmHL7V3InboundConnectivity Map in the schematron sample project.

To Create an Environment

  1. On the NetBeans Services window, right-click CAPS Environments,point to New, and then select Environment.

    A new environmentis created and is added to the CAPS Environment tree.

  2. Rename the new environment to envHL7V3Outbound.

  3. Right-click envHL7V3Outbound, point to New, and then selectLogical Host from the drop-down menu.

    It takesfew seconds to process the Logical Host into the Environment.

    1. Right-click LogicalHost1, point to New, and then selectSun Java System Application Server.

      A new applicationserver (SunJavaSystemApplicationServer1) is added to the EnvironmentExplorer tree under LogicalHost1.

    2. Right-click LogicalHost1, point to New, and then selectSun JMS IQ Manager.

      A new JMS IQ Manager (SunJmsIQMgr1)is added to the Environment tree under LogicalHost1.

  4. Right-click envHL7V3Outbound, point to New, and then selectFile External System.

    1. For the name of the External System, enter esFile.

    2. Click OK.

    The External System is added to the Environment tree.

  5. Right-click envHL7V3Outbound, point to New, and then selectHL7V3 External System.

    1. For the Name of the External System, enter esHL7V3.

    2. Click OK.

    The new External System is added to the Environment tree.

  6. On the NetBeans toolbar, click Save All.

Building and Deploying the Sample Project

Hl7 Message Viewer

Once you create the Environment, you need to create a DeploymentProfile in order to build and deploy the project.

Hl7 Viewer Download

To Build and Deploy the Sample Project

  1. Create a Deployment Profile.

    1. In the NetBeans Projects window, right-click prjHL7V3Inbound,point to New, and then select Deployment Profile.

    2. For the Environment, select envHL7V3Outbound.

    3. For the Connectivity Map, select cmHL7V3Inbound and deselectany other Connectivity Maps.

    4. Click OK.

      The Deployment Profile Editor appears.

  2. Click Automap.

    The Automap Results dialog box appears.

  3. Click Close.

  4. On the NetBeans toolbar, click Save All.

  5. On the Deployment Editor toolbar, click Build.

  6. When the Build confirmation dialog box appears, clickOK.

  7. On the Deployment Editor toolbar, click Deploy.

Executing a Sample Project

To run data through the sample project, you need to use an HL7simulator or HL7 application.

To Execute the Sample Project

  1. Create a sample file named PRPA_IN403001UV01.xml.

  2. Enter the following text into the file (you can copy andpaste this excerpt).


    The above text has been wrapped to fit the page. The followingimage shows the text in an XML editor.

  3. Copy the XML file to a location where the simulator orHL7 application will pick it up.

  4. Open the server log file and check the results at thefollowing location:

    Drivename:JavaCAPS6U1appserverdomainsdomian1logs

    This action displays the following message.

    Schematron Validation Failed