Working With the Standard Inbound and Outbound Sample Projects (V2.x)

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

• Installing the TCP/IP HL7 Adapter and Sample Projects

• Importing the Sample TCP/IP HL7 Adapter Projects

• Creating and Configuring the Environments

• Configuring the Connectivity Map Properties

• Creating the Deployment Profile

• Building and Deploying the Project

• Running the Samples

Installing the TCP/IP HL7 Adapter and Sample Projects

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

The Java Composite Application Platform Suite Installer is a web-based application, used to select and upload adapters and add-on files 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 the Suite Installer but have not installed the Adapter in NetBeans, skip to Installing the TCP/IP Adapter in the NetBeans IDE. If you have installed the Adapter in both the Repository and 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 access the Suite Installer:

   http://localhost:port_number

   where localhost is the TCP/IP host name of the Repository server and not the name of the Repository itself, and port_number is the 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 and the default password is adminadmin.

   ---

   The Java Composite Application Platform Suite Uploader page appears.

4. On the Administration Page, click to Install Additional Products.
   

   The Welcome to the Java Composite Application Platform Suite Uploader page appears.

   
   
5. Expand eWay under the Product Name column, and then select HL7eWay.
   
6. If you are using a version of HL7 other than V2.6, expand OTD and select HL7OTDLibrary along with the HL7 libraries for the version you are using.

   ---

   Note - Note that there are several items to select to install the full V3 HL7 Library.

   ---

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

   The Selecting Files to Install page appears.

   
   
8. Click Browse, and then navigate to and select the SAR file for the listed product. Click Next.
9. Repeat the above steps for each product to install.

   ---

   Note - Based on your previous selection, some dependent products may have been added to the list.

   ---

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

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

Installing the TCP/IP Adapter in the NetBeans IDE

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

To Install the TCP/IP Adapter in the NetBeans IDE

1. Start NetBeans from the Java CAPS home directory.
2. In NetBeans, connect to the Repository (Tools menu > CAPS Repository > 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 CAPS Repository Update Center and deselect all other options.

   If CAPS Repository Update Center does not appear in the list, do the following:

   1. On the Settings page, click Add.

      The Update Center Customizer dialog box appears.

   2. In the Name field, enter CAPS Repository Update Center.
   3. In the URL field, enter the following:

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

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

   4. Click OK.

   ---

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

   ---

6. Click the Available Plugins tab.

   The TCP/IP HL7 components appear in the list.

7. Select the individual components to install, or right-click in the list and select Check All.
8. Click Install.
9. On the NetBeans IDE Installer, click Next, accept the license, and click Install.

   ---

   Note - Ignore any validation or unsigned warnings and continue with the installation.

   ---

10. When the installation completes, click Finish.

    The IDE will restart to complete the installation.

Downloading the Sample Projects

The following instructions provide the steps to download the Enterprise Manager from 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 Adapter Inbound Collaboration Project.
3. Save the prjHL7Inbound.zip file to a local directory.
4. Repeat the previous step for HL7 Adapter Outbound Collaboration Project.
5. If you want to work with the schematron validation Projects for HL7 V3, download HL7 Adapter Inbound Collaboration Project for HL7V3 PRPA_IN403001UV01 With Schematron Validation Enabled.

   ---

   Note - In order to import the V3 projects, you must have the HL7 V3 Libraries installed.

   ---

Importing the Sample TCP/IP HL7 Adapter Projects

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

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

• Importing the TCP/IP Adapter Sample Projects

• Checking Out the Imported Projects

Importing the TCP/IP Adapter Sample Projects

This section describes how to import the standard inbound and outbound 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, the Adapter 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 CAPS Repository, and then select Import Project from the drop-down menu.

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

3. Click Yes to proceed with importing a project.

   The Import Manager appears.

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

   ---

   Note - The associated top-level project is opened in the projects window 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 project of the same name in the CAPS Repository. Determine whether you want to overwrite the existing project. In some cases the imported file will add files to an existing project. If you do not want to overwrite the 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 project is imported, the Import Status dialog box appears.

6. Click OK on the dialog box.

   The CAPS Repository is refreshed.

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

   You should now have two new projects, prjHL7Inbound and prjHL7Outbound, in the tree structure of the projects window, as shown below.

   
   

Checking Out the Imported Projects

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

To Check Out the Imported Projects

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

   The Version Control - Check Out dialog box appears.

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

   ---

   Note - You can select either one or more components.

   ---

3. Click Select All and then click Check Out.

   This checks 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, application servers, and message servers used by a project. These contain the configuration information for these components. Environments are created using NetBeans and the Environment Editor. This section describes how to create and configure Environments for all five of the Connectivity Maps included in the inbound and outbound projects. You only need to create Environments for the operations you want to run.

The instructions are divided into the following sections:

• Creating and Configuring the HL7 Outbound Environment

• Creating Environments for the HL7 Inbound and Outbound Samples

Creating and Configuring the HL7 Outbound Environment

The components required for the HL7 outbound Environment include a Logical Host, application server, JMS IQ Manager, and two external systems.

To Create an Environment for the prjHL7Outbound

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

   A new environment is 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 select Logical Host.

   It takes few seconds to process the Logical Host 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 select Sun Java System Application Server.

      A new application server 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 Password fields.

      The password is defined during Java CAPS installation.

   7. Click OK.
   8. On the Properties Editor, verify the remaining properties and then click OK.
6. Create and configure a JMS IQ Manager:
   1. Right-click lhHL7Outbound, point to New, and then select Sun JMS IQ Manager.

      A new JMS IQ Manager is added to the Environment 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 URL of the IQ Manager.

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

   5. Enter a password as described for the application server above.
   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 select File External System.
   2. On the dialog box that appears, enter esFile as the name.
   3. Click OK.
      

      The external system is added to the Environment tree.

      
      
   4. Right-click esFile and select Properties.

      The Properties Editor appears.

   5. On the Properties Editor, expand Inbound File eWay, and modify the directory from which the File Adapter will pick up the input file.
   6. Click OK.
8. Create and Configure an HL7 External System:
   1. Right-click envHL7Outbound, point to New, and then select HL7 External System.
   2. On the dialog box that appears, enter esHL7 as the name.
   3. Click OK.

      The External System is added to the Environment tree.

      
      
   4. Right-click eHL7 and select Properties.

      The Properties Editor appears.

   5. On the Properties Editor, expand HL7 Outbound eWay, and select TCPIP Outbound Settings.
   6. Make sure the hostname and port are correct for the application that is listening for HL7 messages.
   7. Click OK.
9. On the NetBeans toolbar, click Save All.

Creating Environments for the HL7 Inbound and Outbound Samples

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

HL7 Inbound Sample

Create the envHL7Inbound Environment with the following components:

• HL7 External System

• Logical Host

  • Sun Java System Application Server

  • Sun JMS IQ Manager

HL7 Inbound Forward MSG Sample

Create the envHL7InboundForwardMSG Environment with the following components:

• HL7 External System

• Logical Host

  • Sun Java System Application Server

  • Sun JMS IQ Manager

HL7 Outbound Delayed ACK Sample

Create the envHL7OutboundDelayedACK Environment with the following components:

• HL7 External System

  Configure the HL7 Outbound eWay > TCPIP Outbound Settings properties.

• File External System

  Configure the Inbound File eWay > Parameter Settings properties.

• Logical Host

  • Sun Java System Application Server

  • Sun JMS IQ Manager

HL7 Outbound Forward Sample

Create the envHL7OutboundForward Environment with the following components:

• HL7 External System

  Configure the HL7 Outbound eWay > TCPIP Outbound Settings properties.

• Logical Host

  • Sun Java System Application Server

  • Sun JMS IQ Manager

Configuring the Connectivity Map Properties

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

To Configure the Connectivity Map Properties

1. On the Projects window, expand prjHL7Outbound.
2. Open either cmHL7Outbound or cmHL7OutboundDelayedAck in the Connectivity Map Editor.
3. Double-click the Adapter icon on the line connecting the File External System to the Service.

   The Properties Editor appears.

4. In the Input File Name field, enter the name or the name pattern for the input file.
5. Click OK.

Creating the Deployment Profile

A Deployment Profile is used to assign the connectivity components to the Environment components, including the application server and message server. You only need to create a Deployment Profile for the sample projects that you will run. The following procedure describes how to create a Deployment Profile for the HL7 outbound sample. Connectivity Map and Environment combinations for the other samples are listed at 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.

   The Create 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 deselect all 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 HL7 Inbound and Outbound Samples

Create Deployment Profiles for the remaining TCP/IP HL7 samples following the procedure above and using the following combinations of 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 Deployment Profile:

• Environment: envHL7InboundForwardMSG

• Connectivity Map: cmHL7InboundForwardMSG

HL7Outbound OutboundDelayedACK Sample

Use the following to create the dpOutboundDelayedACK Deployment Profile:

• Environment: envOutboundDelayedACK

• Connectivity Map: cmOutboundDelayedACK

HL7Outbound Forward Sample

Use the following to create the dpHL7OutboundForward Deployment Profile:

• Environment: envHL7OutboundForward

• Connectivity Map: cmHL7OutboundForward

Building and Deploying the Project

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

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

• Starting the GlassFish Server

• Building a Project

• Deploying the Project

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 application server.

1. On the Services window, expand Servers.
2. Right-click GlassFish V2 and select Start.

   The GlassFish server starts. This may take a few minutes

   
   

Building a Project

Once the Deployment Profile is created and the Connectivity Map 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 the errors are listed in the Validation window. Correct any errors and rebuild. Validation errors will occur if you did not open the External System 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, they will be processed.

To Deploy the Project

• On the Deployment Editor toolbar, click Deploy.
  

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

Running the Samples

The inbound and outbound TCP/IP HL7 sample projects demonstrate several different operations. Only deploy the Connectivity Maps that contain the scenario you want to run. For the outbound projects that use a File Adapter, use the following procedure to run data in. For the other projects, you will need an HL7 simulator or HL7 application to 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 the file HL7Msg1.txt (unless you modified the file name in the Connectivity Map properties).

   MSH|^~\&|REGADT|MCM|RSP1P99|MCM|199601051530|SEC|ADT^A44^ADT_A43|00000037|P|2.3.1|
   |||||UTF-8~ISO-8859-1~ISO-8859-2|||c1^sc1&c2
   EVN|A44|199601051530
   PID|||MR2^^^XYZ^MR||JONES^WILLIAM^A^JR||19501010|M|||123 EAST STREET^^NY^NY10021|
   |(212)111-3333|||S|ACCT|1
   MRG|MR1^^^XYZ^MR||ACCT1
   Z01|A44|199601051530

2. Place the sample input file in the configured input directory for the File Adapter.

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

3. Verify the output data from your output directory.

   This sample contains messages that the recipient will accept as valid and properly formatted. The sample messages are used to design the 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 installed on the Enterprise Manager. See Installing Additional Components for Java CAPS 6 for more information.

To Monitor the HL7 Adapters

1. Start the Enterprise Manager.

   ---

   Tip - You can use the start_emanager shortcut in the Java CAPS home directory.

   ---

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

   http://host-name:port-number

   where host-name is the name of the server 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 Java EE > prjHL7Inbound > Deployment1 > cmHL7Inbound, and then select eaHL7Inbound.

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

4. Execute the sample project using an HL7 simulator.
5. Under eaHL7Inbound => jcdHL7inbound1, select Logging to view log messages.
6. Select Alerts to view alerts and their statuses.
7. Select Monitor External Connection to view information about the connection to the external system.

   This action displays the screen as shown below.

   
   
8. Terminate the external system and observe that the status information of the terminated system no longer appears in the status table