Chapter 1 What's New in the Sun TCP/IP HL7 Adapter

The following sections provide instructions on the most significant TCP/IP HL7 release to date For more information, visit the Java CAPS web site at http://goldstar.stc.com/support.

This chapter covers the following topics:

• What's New in This Release.

• Schematron Support in HL7 Adapter.

• Working With the Sample Project.

• Monitoring HL7 External System Connection Status : Inbound Mode.

• Monitoring HL7 External System Connection Status : Outbound Mode.

• Dynamic Connection Support.

• Alert Type TCPIPBASE_SERVER_IDLE_TIMEOUT_EXPIRED.

• HL7 Version 2.6 OTD Library.

• Method to Execute the MLLP V2.0 Database Scripts From GUI.

This chapter covers the following tasks:

• To Manage the Repository.

• To Import the Sample Project.

• To Check Out... the Project.

• To Invoke the Collaboration Editor.

• To Import a Schematron XML and Using it Inside the JCD.

• To Create a HL7 V3 External System.

• To Import a Schematron XML Into the Project.

• To Build and Deploy the Project ZIP Files.

• To Download EMR Files from Java Composite Application Platform Suite.

• To Upload EMR Files to Enterprise Manager.

• To Execute a Sample Project for the Inbound Mode.

• To Execute a Sample Project for the Outbound Mode.

• To Execute a Sample Project for the Alert Code.

• To Connect to the Database.

• To Execute the MLLP V2.0 DB Scripts From GUI.

What's New in This Release

Requires Java CAPS 6 Update 1

Please read this section for the latest updates and additions to the User's Guide available along the following location.

http://developers.sun.com/docs/javacaps/designing/jcapscommadapt.commadapt_tcpiphl7_c.html

The Sun TCP/IP HL7 Adapter includes the following new features:

1. Schematron Support in HL7 Adapter.

2. Dynamic Connection Support.

3. HL7 External System Connection Status Monitoring.

4. Monitoring Alert Code Type.

5. Newly Added HL7 Version 2.6 OTD Library.

6. Method to Execute the MLLP V2.0 Database scripts from GUI.

Schematron Support in HL7 Adapter

This topic helps users validate the Schematron configuration in HL7 adapter.

Schematron Overview

The Schematron uses the concept of finding tree patterns in the parsed document rather than the grammar. This approach allows representation of numerous structures that are inconvenient and difficult in grammar-based schema languages.

Example:

<?xml version="1.0" encoding="UTF-8"?><Person><Name>Eddie</Name><Gender>Male</Gender><Person>

The above example is an XML document. This xml document can be validated against the below schematron:

<?xml version="1.0" encoding="UTF-8"?><sch:schema xmlns:sch="http://www.ascc.net/xml/schematron"><sch:pattern name="Check structure"><sch:rule context="Person"><sch:assert test="@Title">The element Person must have a Title attribute<sch:assert><sch:assert test="count(*) = 2 and count(Name) = 1 and count(Gender) = 1">he element Person should have the child elements Name and Gender.<sch:assert><sch:assert test="*[1] = Name">The element Name must appear before elementGender.</sch:assert></sch:rule></sch:pattern></sch:schema>

In HL7 adapter, this schematron is useful for validating a HL7 V3 document against predefined schematron schemas. Users can write these schematron schemas. These can be obtained from organizations like NHS, HL7 org. For example, NHS provides few schematrons for CDA documents.

Schematron Configuration in HL7 Adapter

The schematron validation is configured from the Connectivity Map Properties dialog box.

There are two properties listed for Schematron support:

1. Schematron Validation: Enabled or Disabled.

   This opens the Enable Schematron Validation LDAP Setting box. When Enabled the Schematron Configuration is performed.

   Provide the LDAP Reference value. Prefix ldap:// or ldaps:// when providing a LDAP reference.

   ---

   Note –

   This is not case sensitive.

   ---

   

2. Schematron Files: Provide the list of schematron files. Use commas to separate multiple files.

   

   Example, checkprofileid.xml

   Change the extension to .xml.

   Click OK.

3. Click OK.

To Manage the Repository

Before You Begin

The below steps explains about Schematron support using a sample project prhHL7V3Inbound_WithSchematron.zip.

The sample project comes along with the HL7eWay.sar. This can be downloaded from the Downloads tab from the SAR uploader GUI.

1. Upload the .sar files to the Repository and download sample project from the repository.

   ---

   Note –

   For detailed instructions, see Installing the TCP/IP HL7 Adapter and Sample Projects in Sun Adapter for TCP/IP HL7 Tutorial.

   Ensure the required HL7 V3 SAR files are uploaded to the repository.

   • HL7eWay.sar

   • HL7OTDLibrary.sar

   • HL7OTDLibraryGeneric.sar

   • HL7V32006PatientAdmin.sar

   • HL7V32006TransInfra.sar

   ---

2. Click the Downloads tab on the Suite Uploader.

   Click on HL7 Adapter Inbound Collaboration Project for HL7V3 PRPA_IN403001UV01 With Schematron Validation Enabled and save prjHL7V3Inbound_WithSchematron.zip to a local directory.

API for Schematron Validation

There is a new API added in HL7 adapter for schematron validation. This API is a wrapper of the Open source XSLT based API available at http://xml.ascc.net/schematron/1.5. The API is an XSL file called metastylesheet (skeleton1-5.xsl) . Applying the metastylesheet to the schematron xml document generates another xsl file. This xsl file can be applied to the input xml document to validate, which produces the output xml document.

This metastylesheet can be extended and overridden so that you can customize the output xml document.

The output xml document contains details of all the validation failures. This document can be embedded inside the V3 acknowledgement and can be sent to the original sender.

Example,

A resultant xml document generated after invoking the api using the XML document and the schematron document mentioned in the overview section. The xml document will look as follows -

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schematron-output phase="#ALL" schemaVersion="" title="" xmlns:
sch="http://www.ascc.net/xml/schematron">
<active-pattern name="Check structure"/>
<fired-rule context="Person" id="" role=""/>
<failed-assert id="" role="" test="@Title" location="/@Person[1]">
<text>The element Person must have a Title attribute</text>
</failed-assert>
<schematron-output>

Using the Schematron API

Use the methods mentioned below ton invoke the schematron API from the JCD. The following are discussed.

• Obtaining the Factory Object

• Obtaining the Validator Object

• Performing the Validation

Obtaining the Factory Object

com.stc.connector.hl7.schematron.SchematronValidatorFactory factory = com.stc.connector.hl7.schematron.SchematronValidatorFactory.getSchematronValidatorFactory();

Obtaining the Validator Object

com.stc.connector.hl7.schematron.SchematronValidator validator = factory.getDefaultValidator( domSource );

domSource is the DOMSource object of the schematron XML.

Performing the Validation

com.stc.connector.hl7.schematron.ValidationOutput output = validator.validate( dataSrc );

dataSrc is a Source of the payload. The payload can be an entire V3 XML document or a CDA document.

The ValidationOutput object contains the resultant XML document as well as a method is Valid() which returns values when the validation has passed or failed.

Working With the Sample Project

This sample project receives a HL7 V3 message PRPA_IN403001UV01 and sends a HL7 V3 ACK or NAK (MCCI_IN000004UV01). This project is same as prjHL7V3Inbound except that the schematron validation for the input xml.

To Import the Sample Project

1. Create CAPS Environment in the Services tab.

   See To Create a HL7 V3 External System for procedural description.

2. Import the project file.

   For steps to import the sample Project ZIP file, see Importing the Sample TCP/IP HL7 Adapter Projects in Sun Adapter for TCP/IP HL7 Tutorial.

   In the current example, prjHL7V3Inbound_WithSchematron.

3. Expand the tree node.

   The illustration is as shown.

   

   ---

   Note –

   The JAR file is bundled in the project.

   For example, checkprofileid.jar

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

   ---

To Check Out... the Project

1. Select prjHL7V3Inbound_WithSchematron —> cmHl7V3Inbound.

   SeeChecking Out the Imported Projects in Sun Adapter for TCP/IP HL7 Tutorial for steps to check out project components.

2. Double-click cmHL7V3Inbound.

   The action displays the screen shown below.

   

3. Double-click on the node found between eaHL7V3Inbound and jcdHL7V3Inbound1.

   This action opens the properties screen for the Schematron.

   

4. Click the ellipses (...) to modify the Properties.

   1. Schematron Validation: Enable

   2. Schematron Files: Provide a list of Schematron files. Use comma to separate multiple files.

Editing the JCD

The JCD is edited as described in the steps below.

To Invoke the Collaboration Editor

1. Select the node jcdHL7V3Inbound and double-click on it.

   

   This action invokes the Collaboration Editor and displays the Java source.

   

Schematron Validation Inside the JCD

The schematron validation API is invoked from the JCD. This validation follows the normal HL7 V3 validation. It is invoked only when the Enable Schematron Validation property is true. This validation scans the schematronfiles list and invokes the method validateWithSchematron() depending on the value set forth for the property.

Validating the Code Snippet

boolean validated = validateHL7Message( HL7message );
java.util.ArrayList outputList = new java.util.ArrayList();
if (validated) {
boolean schematronValidationEnabled =
input.getHL7v3MessageInfo().getSchematronValidationInfo().
isSchematronValidationEnabled();
log( LOG_LEVEL_INFO, "SchematronEnabled = " + schematronValidationEnabled );
if (schematronValidationEnabled) {
String[] schFiles =
input.getHL7v3MessageInfo().getSchematronValidationInfo().getSchematronFilesList();
log( LOG_LEVEL_INFO, "schFilesList  = " + schFiles );
for (int i = 0; i < schFiles.length; i++) {
log( LOG_LEVEL_INFO, "Adding schematron file for validation  = " + schFiles[i] );
com.stc.connector.hl7.schematron.ValidationOutput output =
validateWithSchematron( "/" + schFiles[i], HL7message );
outputList.add( output );
}

for (int i = 0; i < outputList.size(); i++) {
com.stc.connector.hl7.schematron.ValidationOutput output =
(com.stc.connector.hl7.schematron.ValidationOutput) outputList.get( i );
if (!output.isValid()) {
validated = false;
schematronValidationError = true;
log( LOG_LEVEL_INFO, "Schematron Validation failed." );
break;
} else {
validated = true;
}
}

The illustrations are as shown.

Validating With Schematron Method

The Schematron method invokes the Schematron API. It reads the schematron files from classpath and constructs a DOM source. The DOM source passes it to obtain the SchematronValidator object. The object invokes the validate() method to pass the hl7payload.

validateWithSchematron() method

private com.stc.connector.hl7.schematron.
ValidationOutput validateWithSchematron( String
 schematronFile, byte[] hl7payload )
throws Exception
{
com.stc.connector.hl7.schematron.SchematronValidatorFactory 
factory =
com.stc.connector.hl7.schematron.SchematronValidatorFactory.
getSchematronValidatorFactory();
log( LOG_LEVEL_INFO, "Schematron URI :" +
this.getClass().getResource( schematronFile ).toString() );
java.io.InputStream in = this.getClass().
getResourceAsStream( schematronFile );
java.io.BufferedReader bufReader = new java.io.
BufferedReader( new
java.io.InputStreamReader( in ) );
StringBuffer schematronXml = new StringBuffer();
String line = bufReader.readLine();
while (line != null) {
schematronXml.append( line );
line = bufReader.readLine();
}

bufReader.close();

javax.xml.parsers.DocumentBuilderFactory 
domBuilderFactory =
javax.xml.parsers.DocumentBuilderFactory.
newInstance();
domBuilderFactory.setNamespaceAware( true );
org.w3c.dom.Document doc = domBuilderFactory.
newDocumentBuilder().parse( new
org.xml.sax.InputSource( new java.io.ByteArrayInputStream
( schematronXml.toString().getBytes() ) ) );
javax.xml.transform.dom.DOMSource domSource = new
javax.xml.transform.dom.DOMSource( doc.
getDocumentElement() );
com.stc.connector.hl7.schematron.SchematronValidator 
validator =
factory.getDefaultValidator( domSource );
javax.xml.transform.stream.StreamSource dataSrc = new javax.xml.
transform.stream.StreamSource(
new java.io.ByteArrayInputStream( hl7payload ) );
com.stc.connector.hl7.schematron.ValidationOutput output = 
validator.validate( dataSrc );
return output;
}

The illustrations are as shown.

Retrieving the Resultant XML Document

The makeNAK() method retrieves the Resultant XML document generated from the Schematron validation. The XML document is embedded in the AcknowledgementDetail section of HL7V3 Acknowledgement XML.

makeNAK() method

if (schematronValidationError) {
log( LOG_LEVEL_INFO, "Schematron validationOutputList.size=" 
+ validationOutputList.size()
);
or (int i = 0; i < validationOutputList.size(); i++) {
// otd_MCCI_IN000004UV01_1.getAcknowledgement(0).
addAcknowledgementDetail();
com.stc.connector.hl7.schematron.ValidationOutput output =
(com.stc.connector.hl7.schematron.ValidationOutput) 
validationOutputList.get( i );
String outputStr = output.getOutputAsString();
otd_MCCI_IN000004UV01_1.getAcknowledgement( 0 ).
getAcknowledgementDetail( i ).getTypeCode().setCode( "E" );
otd_MCCI_IN000004UV01_1.getAcknowledgement( 0 ).
getAcknowledgementDetail( i ).getCode().setCode
( "Validation Failure: Schematron Validation Failed" );
otd_MCCI_IN000004UV01_1.getAcknowledgement( 0 ).
getAcknowledgementDetail( i ).getText().setMediaType( "text/xml" );
otd_MCCI_IN000004UV01_1.getAcknowledgement( 0 ).
getAcknowledgementDetail( i ).getText().setX__PCDATA__MX( outputStr );
log( LOG_LEVEL_INFO, "Schematron Validation Output = " 
+ outputStr );
}
}

Sample Schematron

<?xml version="1.0" encoding="UTF-8"?><sch:schema xmlns:sch="http://www.ascc.net/xml/schematron"><sch:ns prefix="hl7v3" uri="urn:hl7-org:v3"/><sch:pattern name="Check structure"><sch:rule context="hl7v3:PRPA_IN403001UV01"><sch:assert test="count(hl7v3:profileId) = 1">The profileId should be present. It is missing.</sch:assert></sch:rule></sch:pattern></sch:schema>

This schematron checks for the presence of the <profileId> tag under PRPA_IN403001UV01 tag.

Sample Input Document

<PRPA_IN403001UV01 xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3 PRPA_IN403001UV01.xsd"><id root="1.1.2.3.4.6" extension="5929" assigningAuthorityName="Litware Inc."/><creationTime value="20050303180027"/><versionCode code="V3PR1"/><interactionId root="1.1.6.7.8" extension="PRPA_IN403001UV01" assigningAuthorityName="HL7"/><profileId root="1.1.1.1"/><processingCode code="D"/><processingModeCode code="T"/><acceptAckCode code="AL"/>.........

To Import a Schematron XML and Using it Inside the JCD

This is for users who want to create the checkprofileid.jar.

1. Create a JAR file containing the Schematron XML.

2. Import the ZIP file from File —> Import.

3. Open the JCD Editor and click Add JAR.

   This will add the JAR file to the JCD.

   

To Create a HL7 V3 External System

1. Click the CAPS Environment from the Services tab.

2. Right-click and select New Environment.

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

3. Rename the new environment to envHL7V3Outbound or retain the default name.

4. Right-click envHL7V3Outbound or Environment1 and select New. Choose LogicalHost from the drop-down menu.

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

   1. Right-click LogicalHost1 and select New. Choose Sun Java System Application Server from the drop-down menu.

      A new Application Server (SunJavaSystemApplicationServer1) is added to the Environment Explorer tree under LogicalHost1.

   2. Right-click LogicalHost1 and select New. Choose Sun JMS IQ Manager from the drop-down menu.

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

5. Right-click envHL7V3Outbound or Environment1 and select New. Choose File External System.

   1. Enter the Name for the External System as esFile.

   2. Click OK.

   A new node esFile is added to the Environment Editor.

6. Right-click envHL7V3Outbound or Environment1 and select New. Choose HL7V3 External System.

   

   1. Enter the Name for the External System as esHL7V3.

   2. Click OK.

   A new node esHL7V3 is added to the Environment Editor.

7. Click envHL7V3Outbound or Environment1 on the right pane to view the complete structure of the new nodes.

8. Click on File menu and select Save All to save all the changes made to the environment.

To Import a Schematron XML Into the Project

1. Create a Deployment Profile.

   See Building and Deploying the Sample Project in Sun Adapter for TCP/IP HL7 Tutorial for steps on creating a deployment profile.

   ---

   Note –

   Make sure that the selected Environment: is envHL7V3Outbound and the selected Connectivity Map: is cmHL7V3Inbound.

   ---

   The illustration is as shown.

   

2. Click OK.

3. Click Automap.

   

   This displays the Automap Results dialog box.

   

4. Click Close.

5. Click Save All.

6. Click the Build button.

   See Building and Deploying the Sample Project in Sun Adapter for TCP/IP HL7 Tutorial for steps on building the project.

   This action displays the Project build confirmation message.

   

7. Click OK.

8. Click the Deploy button.

   ---

   Tip –

   Make sure the GlassFish server is started before deploying.

   ---

Executing a Sample Project

The steps describe the method to build and deploy the compressed (.zip) project files, prjHL7V3Inbound_WithSchematron.zip and prjHL7V3Outbound.zip.

To Build and Deploy the Project ZIP Files

1. Upload the latest HL7eWay.sar from the Java Composite Application Platform Suite Uploader.

2. Install the new NBMs into the NetBeans IDE from the CAPS Repository.

3. Import the project prjHL7V3Inbound_WithSchematron.zip and prjHL7V3Outbound.zip.

   Follow the steps described in Schematron Validation Inside the JCD.

4. Create the Deployment Profiles.

5. Build and Deploy both the projects.

6. Use the sample HL7V3 message to trigger the project. Use Copy and Paste. Copy the file into C:\temp. Name the file as PRPA_IN403001UV01.xml:

   ---

   Note –

   Copy and Paste the content to Notepad File and name the file as PRPA_IN403001UV01.xml. Ensure to change the extension from TXT to XML.

   ---

   Sample XML File

   <?xml version="1.0" encoding="UTF-8"?><PRPA_IN403001UV01 xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3 PRPA_IN403001UV01.xsd"><id root="1.1.2.3.4.6" extension="5929" assigningAuthorityName="Litware Inc."/><creationTime value="20050303180027"/><versionCode code="V3PR1"/><interactionId root="1.1.6.7.8" extension="PRPA_IN403001UV01" assigningAuthorityName="HL7"/><!--profileId root="1.1.1.1"/--><processingCode code="D"/><processingModeCode code="T"/><acceptAckCode code="AL"/><receiver typeCode="RCV"><device classCode="DEV" determinerCode="INSTANCE"><id root="1.4.7.8.3"/></device></receiver><sender typeCode="SND"><device classCode="DEV" determinerCode="INSTANCE"><id root="1.45.6.7.98"/></device></sender><controlActProcess classCode="CACT" moodCode="EVN"><subject typeCode="SUBJ" contextConductionInd="false"><encounterEvent classCode="ENC" moodCode="EVN"><id root="1.56.3.4.7.5" extension="122345" assigningAuthorityName="Maple Hospital Emergency"/><code code="EMER" codeSystem="2.16.840.1.113883.5.4"/><statusCode code="active"/><subject contextControlCode="OP"><patient classCode="PAT"><id root="1.56.3.4.7.9" extension="55321" assigningAuthorityName="Maple Hospital Patients"/><patientPerson classCode="PSN" determinerCode="INSTANCE"><name><given>Rob</given><given>P</given><family>Young</family></name><administrativeGenderCode code="M" codeSystem="2.16.840.1.113883.5.1"/><birthTime value="19800309"/></patientPerson></patient></subject></encounterEvent></subject></controlActProcess></PRPA_IN403001UV01>

   

   The logical processing is as follows:

   1. Place the .xml file in C:\temp.

   2. Open the server log file and check the results at the following location:

      Drivename:\JavaCAPS6U1\appserver\domains\domian1\logs

      This action displays the following message.

      Schematron Validation Failed

Monitoring HL7 External System Connection Status : Inbound Mode

This feature describes monitoring the external system connection status from the Enterprise Manager GUI when the HL7 Adapter is deployed in an inbound mode.

• HL7 Adapter emr plugin is extended to provide the monitoring external system connection status

• Provision is included in the Enterprise Manager GUI for monitoring the HL7 external system connection status

• Click the Monitor HL7 External Connection link. The user will see all the external systems (HL7 clients) connected to the HL7 inbound adapter (HL7 Server)

• When the connection with the external system is lost, its status information will not appear in the status table shown in the Enterprise Manager GUI.

Managing the Repository

This section explains the method to manage the Repository.

To Download EMR Files from Java Composite Application Platform Suite

1. Enter the Host Address http://localhost:portnumber

   The default portnumber is 12000.

2. Enter the User Name and Password.

   The default User Name is Administrator and Password is STC.

3. Click Downloads tab and select the following from the list.

   1. eWays Base Enterprise Manager Plug-in

   2. HL7 eWay Enterprise Manager Plug-in

4. Save the emr files to the local directory.

   ---

   Note –

   User can also locate the emr files from the local directory, if these are installed during Java CAPS installation.

   Follow the path to pick the already installed HL7eWay.emr from the local directory,

   Drive:/JavaCAPSR6U1/repository/repository/data/files/InstallManager/HL7eWay/downloadables/com.stc.HL7eWay.emr

   The emr file is installed during Java CAPS installation.

   ---

To Upload EMR Files to Enterprise Manager

1. Start the eManager from the following location: Drivename:/JavaCAPSR6U`/eManager/startserver.bat

   Double-click startserver.bat.

2. Invoke any Web Browser and enter the URL to start the Java CAPS Enterprise Manager.

   http://localhost:port number

   For example, the port number is 15000

3. Enter the User ID and Password.

   The default User ID is admin and default Password is adminadmin.

4. Install the HL7eWay.emr from the Java CAPS Repository to the Enterprise Manager.

   1. Click Web Application Manager from Java CAPS Enterprise Manager —> Manage Applications.

   2. Click Browse to select the com.stc.HL7eWay.emr from the local directory.

      This file is downloaded from the Java Composite Application Platform Suite.

   3. Click Deploy.

   4. Click Web Application Manager.

      Enter all the required credentials like Host Name, User Name, and Password.

   5. Click Connect.

      The list of Management Applications available for installation from the Repository is displayed.

   6. Select eWays Base Enterprise Manager Plug-in and HL7 eWay Enterprise Manager Plug-in.

      ---

      Note –

      Ensure to select eWay Base Enterprise Manager Plug-in. If not installed the application generates an error message.

      Select an appropriate eWay Monitor Plug-in and check the version of the .sar file.

      ---

      

   7. Click Install.

   See Using Enterprise Manager Management Application in Java CAPS for detailed procedures.

   This installs the eWay Base Enterprise Manager Plug-in and HL7eWay Enterprise Manager Plug-in from Java CAPS Repository to the Enterprise Manager.

Executing a Sample Project : Inbound Mode

Create a sample project to use the uploaded HL7eWay.sar

To Execute a Sample Project for the Inbound Mode

1. Install HL7eWay.sar file to the Sun Java CAPS Repository.

   For steps, see Installing the TCP/IP HL7 Adapter and Sample Projects in Sun Adapter for TCP/IP HL7 Tutorial.

2. Start the NetBeans IDE and use the NetBeans Plugins Manager to install the HL7 adapter nbms to NetBeans IDE.

3. Re-start the Netbeans IDE and establish connection to the Sun Java CAPS Repository.

4. Create a CAPS Environment for the prjHL7Inbound project.

   

5. Import the HL7 project prjHL7Inbound.zip that is bundled with HL7eWay.sar into NetBeans IDE

   

6. Create the Deployment Profile and select Check Out...

   The Check Out... option enables users to modify the created Deployment Profile for prjHL7Inbound.

   1. Enter the Deployment Profile Name and select the Environment from the drop-down menu.

   2. Select the check box to choose the Used Connectivity Map cmHL7Inbound.

   3. Click OK.

7. Click the Automap button to map the created environment files.

   ---

   Note –

   Ensure to start the GlassFish V2 sever before deploying.

   ---

8. Click Build to build the project.

   The following message is displayed after the build is successful.

   Project buld was successful (elapsed time: 120.562 seconds).

   

9. Click OK.

10. Click Deploy button to deploy the project onto GlassFish V2 Application Server from the NetBeans IDE.

    This action displays the following message.

    Project deployment successful (elaspsed time: 49 seconds).

11. Open a Web Browser and login to the Enterprise Manager at the following path:

    http://localhost:portnumber

    The default portnumber is 15000.

12. Expand the tree from the Explorer frame of the eManager GUI and select the prjHL7Inbound/Deployment1/cmHL7Inbound/eaHL7Inbound external system.

13. Select the Monitor external Connection action of the tree from the eaHL7Inbound => jcdHL7inbound1 frame.

    This action displays the screen as shown below.

    

14. Start multiple HL7 external system and continue to send requests to the HL7 inbound project. Follow the Monitor External Connection link to observe the status of the external systems connection.

15. Terminate one of the external systems and observe that the status information of the terminated system does not appear in the status table

16. Execute the sample project using HL7 Simulator.

    Here, is a sample illustration.

    

Monitoring HL7 External System Connection Status : Outbound Mode

This feature is meant to monitor the connectivity status of external systems from the Enterprise Manager GUI when the HL7 Adapter is deployed in the outbound mode.

• HL7 Adapter emr plugin has been extended to provide the monitoring external system connection status

• Provision is included in the Enterprise Manager GUI for monitoring the HL7 external system connection status

• Click on the monitoring HL7 external system connection link. A scheduler thread is invoked which executes periodic monitoring action. The default monitoring period retrieved from the HL7 adapter we bapplication's deployment descriptor web.xml

• In case they have to supply their own monitoring period, they have to stop the current monitoring thread.

Code in Web.xml

<web-app>
...
...
<!--  Default monitoring period used in monitoring the 
external system connection  -->
<context-param>
<param-name>monitorperiod</param-name>
<param-value>2000</param-value>
</context-param>
...
</web-app>

Executing a Sample Project : Outbound Mode

Create a sample project to use the uploaded HL7eWay.sar

To Execute a Sample Project for the Outbound Mode

1. Install HL7eWay.sar file to Sun Java CAPS Repository.

   For steps, see Sun Adapter for TCP/IP HL7 Tutorial.

2. Start the NetBeans IDE. Use the NetBeans PlugIns Manager to install the HL7 adapter nbms to NetBeans IDE.

3. Re-start the Netbeans IDE and establish connection to the Sun Java CAPS Repository.

4. Create a CAPS Environment for the prjHL7Outbound project.

   

5. Import the sample HL7 project prjHL7Outbound.zip that is bundled with HL7eWay.sar into NetBeans IDE

   

6. Create Deployment Profile and select Check Out...

   The Check Out... option enables the user to modify the created Deployment Profile for prjHL7Outbound.

   1. Enter the Deployment Profile Name and select the Environment from the drop-down menu.

   2. Choose the Used Connectivity Map cmHL7Outbound by selecting the check box.

   3. Click OK.

7. Click Automap button to map the created environment files.

   ---

   Note –

   Ensure to start the GlassFish V2 sever before deploying.

   ---

8. Click Build to build the project.

   The following message indicates that the build was successful.

   Project buld was successful (elapsed time: 13.687 seconds).

   

9. Click OK.

10. Click Deploy button to deploy the project onto GlassFish V2 Application Server from NetBeans IDE.

    The action displays the following message.

    Porject deployment successful (elaspsed time: 45 seconds).

11. Repeat steps 11 through 17 of prjHL7Inbound. See Executing a Sample Project : Inbound Mode.

12. Open a Web Browser and login to the Enterprise Manager at the following path:

    http://localhost:portnumber

    The default portnumber is 15000.

13. Click Refresh Rate

    The illustration is as shown.

    

14. Expand the tree from the Explorer frame of the eManager GUI. Select the prjHL7Outbound/Deployment1/cmHL7Outbound/eaHL7Outbound external system.

15. Select the Monitor external Connection action of the tree from the jcdHL7Outbound —> eaHL7Outbound frame.

    This triggers an executor thread that monitors the external system connection. The user observes the latest status in the GUI.

    The screen is displayed as shown.

    

16. Click Stop Monitoring to exit the listening of TCPIP Server Monitor Task.

    The Monitoring Period is displayed in milliseconds.

17. Execute the sample project using HL7 Listener.

    Here, is a sample illustration.

    

Dynamic Connection Support

The Dynamic Connection Support feature is added to both TCPIP and HL7 Adapters.

Dynamic Connection support features the following.

1. Users can provide the host and port details and dynamically connect to the external system.

2. The following new methods are added.

   1. setHost(String ipaddress or hostname)

   2. setPort(int number)

   3. connect()

   4. connect(String host, int port)

   5. Close()

3. An environment configuration property called Connection Mode is added.

   The value can be Automatic or Manual.

4. The Dynamic Connection Support is available only if Connection Mode is Automatic.

   Default Value is Automatic

5. An exception is generated if the methods setHost, setPort,connect() are invoked when the ConnectionMode is Automatic.

6. If the connect() method is invoked without invoking setHost() and setPort(). The adapter uses the environment properties to connect to the host and port.

Code in JCD

TCPIPClient_1.connect( "localhost", 9999 );
// send handshake string
TCPIPClient_1.sendEnvelopedMsg( "Sun",getBytes() );
//receive handshake string
byte[] back = TCPIPClient_1.receiveEnvelopedMesg();
...
...
...
TCPIPClient_1.close();
TCPIPClient_1.connect( "129.158.239.67", 9999 );
// send handshake string
TCPIPClient_1.sendEnvelopedMesg( "Sun",getBytes() );
// receive handshake string
back = TCPIPClient_1.receiveEnvelopedMesg();
...
...
....
TCPIPClient_1.client();

Alert Type TCPIPBASE_SERVER_IDLE_TIMEOUT_EXPIRED

The HL7 adapter is enhanced to generate an alert when no messages are received from the HL7 client with in the configured idle time-out period (threshold).

• A new alert type TCPIPBASE_SERVER_IDLE_TIMEOUT_EXPIRED has been added

• This alert is generated on expiry of the time-out period specified in Connectivity Map property: HL7 Inbound Configuration --> TCPIP Inbound Settings --> Inbound Connection Management --> idle timeout

• User must connect to the GlassFish Application Server to where the HL7 server application is deployed. View the alert from the eManage GUI.

To Execute a Sample Project for the Alert Code

1. Install HL7eWay.sar file to Sun Java CAPS Repository.

2. Start the NetBeans IDE and install the HL7 adapter nbms to NetBeans IDE.

3. Re-start the NetBeans IDE and establish connection to the Sun Java CAPS Repository.

4. Import the sample HL7 project prjHL7Inbound.zip that is bundled with HL7eWay.sar into NetBeans IDE.

   

5. Double-click on the node to invoke the Configuration Properties.

   

6. Click OK.

7. Click prjHL7Inbound to build and deploy the project to the GlassFish Application Server.

8. Send messages to HL7 inbound project continuously from HL7 External System.

9. Start Java CAPS Enterprise Manager and install the HL7eWay emr from Java CAPS Repository to Enterprise Manager.

10. Connect to GlassFish Application Server where the project is deployed from Enterprise Manager.

11. Stop sending the message from HL7 External System.

    Since there were no messages received from the HL7 External System within the configured idletimeout period, HL7 adapter will generate an alert.

12. Select the prjHL7Inbound/Deployment1/cmHL7Inbound/eaHL7Inbound external system from the explorer frame of the eManager GUI.

13. Select the Alerts link from the tree. An alert of type TCPIPBASE_SERVER_IDLE_TIMEOUT_EXPIRED is displayed in alerts table from the eaHL7Inbound=>jcdHL7inbound1 frame.

See Also

Message Code: TCPIPBASE-SERVER-IDLE-TIMEOUT-EXPIRED000008

Description: No message received from the peer within in the specified idle timeout value <60000>. So the connection with the peer is being terminated.

HL7 Version 2.6 OTD Library

This topic provides a complete list of HL7 v2.6 OTD Library.

Method to Execute the MLLP V2.0 Database Scripts From GUI

This topic describes the steps to execute the MLLP V2.0 Database Scripts from GUI. The Database is used when a user wants to use HL7eWay.sar with MLLP V2.0 transport scenarios.

Working With the Java DB (Derby) Database in NetBeans IDE

This topic demonstrates the method to set up a connection to Sun's Java Database (which is based on the Apache Derby database) in NetBeans IDE. Once a connection is established, the user begins to work with the database in the IDE.

To Connect to the Database

1. Click the Services tab and expand the Databases node to connect to the Derby Database.

   

   ---

   Note –

   A broken icon represents that the database is not connected.

   ---

2. Right-click the database connection node (jdbc:derby://localhost:1527/sample [app on APP) and choose Connect.

   The connection is established successfully and is as shown in the figure.

   

To Execute the MLLP V2.0 DB Scripts From GUI

1. Click the Projects tab.

2. Expand and click CAPS Components Library.

3. Select and expand Adapters.

4. Select and expand HL7.

5. Select and right-click derby_install.sql. from Database Scripts.

6. Click Open.

   

   This opens the derby_install.sql editor window along with the SQL Statement.

   CREATE TABLE HL7MESSAGELOG (MESSAGEID VARCHAR(250), APPLICATIONID VARCHAR(250) , REQUESTMESSAGE CLOB, RESPONSEMESSAGE CLOB, STATUS SMALLINT, CREATEDTIME TIMESTAMP, LASTUPDATEDTIME TIMESTAMP)

7. Choose the Database Connection from the drop-down list.

8. Click the Run button.

   

   The following message is displayed.

   SQL statement(s) executed successfully.