test

Sun Adapter for TCP/IP HL7 Tutorial

Working With the Schematron HL7 V3 Sample Project

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

Follow these steps in the order given to complete the schematron sample:

Importing the Sample Project

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

ProcedureTo Import the Sample Project

Before You Begin

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

  1. If the TCP/IP HL7 Adapter is not already installed, install it 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 V3 outbound 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 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.

      The Import Manager appears.

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

    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. Close the Import Manager.

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

      Display of Tree Node
    Note –

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

Checking Out the Project

When you first import a project, all of its components are checked in to version control. This means you cannot edit the project. You need to check the components out first.

ProcedureTo 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

ProcedureTo Modify the Connectivity Map

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

    The Connectivity Map appears in the Connectivity Map Editor.

    Schematron Connectivity Map

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

    The Properties Editor appears.

    Schematron Validation Properties

  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 multiple files.

Modifying the Java Collaboration Definition

The JCD is edited as described in the steps below.

ProcedureModify 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.

    The following sections describe parts of the JCD that define schematron validation.

Schematron Validation Inside the JCD

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

Excerpt for Beginning Schematron Validation


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 above text has been wrapped for display purposes. The images below show the code as it appears in the Collaboration Editor.

Inside the JCDInside the JCD

validateWithSchematron() 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. The following excerpt from the JCD defines the validation 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 above text has been wrapped for display purposes. The images below show the code as it appears in the Collaboration Editor.

Validate With SchematronValidate With Schematron

Retrieving the Validation Results

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

makeNAK() method 


if (schematronValidationError) {
   log( LOG_LEVEL_INFO, "Schematron validationOutputList.size=" 
     + validationOutputList.size());
   for (int i = 0; i < validationOutputList.size(); i++) {
      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 );
   }
}

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

Properties of makeNAK

Creating and Importing Sample Files

This section provides sample schematron validation and input files, and also gives instructions on importing the validation file for use in the JCD.

Sample Schematron

Below is a sample schematron validation file that checks for the presence of the profileid field in the PRPA_IN403001UV01 OTD.


<?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>

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"/>
...
...
...
Note –

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

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 file and package it for the JCD.

ProcedureTo Import a Schematron XML and Add it to the JCD

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

  2. Do the following to import the JAR file:

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

    2. Navigate to and select the JAR file.

    3. Click Select, and then click Import.

      The file now 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 click Import.

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

Creating the Environment

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

ProcedureTo Create an Environment

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

    A new environment is 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 select Logical Host from the drop-down menu.

    It takes few seconds to process the Logical Host into the Environment.

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

      A new application server (SunJavaSystemApplicationServer1) is added to the Environment Explorer tree under LogicalHost1.

    2. Right-click LogicalHost1, point to New, and then select Sun 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 select File 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 select HL7V3 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

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

ProcedureTo 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 deselect any other Connectivity Maps.

      Deployment Profile

    4. Click OK.

      The Deployment Profile Editor appears.

  2. Click Automap.

    Automap Properties

    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, click OK.

  7. On the Deployment Editor toolbar, click Deploy.

Executing a Sample Project

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

ProcedureTo Execute the Sample Project

  1. Create a sample file named PRPA_IN403001UV01.xml.

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


    <?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 above text has been wrapped to fit the page. The following image shows the text in an XML editor.

    Properties of XMLCode

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

  4. 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