Data Normalization Pipeline 1.0 Connectivity Software

From SHARP Project Wiki
Jump to navigationJump to search

THIS PAGE IS UNDER CONSTRUCTION

Overview

Connectivity software install gets you steps 1, 2, 4, and 5 as seen in the overview. We have chosen Mirth Connect as the application to move original data to the right place and in the right format for the Data Normalization pipeline. Mirth Connect serves as a hub. Incoming data is recognized, potentially transformed, and sent to a processing location. Channels are set up to serve this purpose. The connectivity software also serves to take CEM objects off the end of the Data Normalization pipeline and place them in to various other formats, for example, in a DBMS.

(Optional) Getting data to arrive at the system where the Data Normalization pipeline can process it is left to the user. If you require a Gateway to Gateway exchange from one location to another, NwHIN could be used. This was tested successfully using a non-secure gateway by the SHARPn group. If you choose NwHIN Connect, then it must be setup prior to the installation and configuration of Mirth Connect given that you are using the standard SHARP deployment, configuration artifacts, and installation instructions.

Prerequisites

  1. Installing the connectivity software requires an existing pipeline (steps 3 in the overview).
  2. NwHIN Aurion Connect is NOT required, however, the instructions below assume that this was already done. In order to complete the install below WITHOUT installing Aurion Connect, create an empty directory at the root called "/nhin" and then get started.
  3. Oracle's Sun Java 1.6 or greater runtime. Mirth Connect FAQ.
  4. Root level authority on your system.

These instructions require the following artifacts: NEED TO MOVE THESE FILES TO SVN RATHER THAN THE SHARP WEB SITE

Install Mirth Connect

  1. In order to provide a cohesive install for Data Normalization a specific folder structure is required.
    1. Create the following directories:
      • /nhin
      • /nhin/mirthconnect
    2. Change permissions on /nhin/mirthconnect
      • chmod 774 /nhin
      • chmod 774 /nhin/mirthconnect
  2. Install Mirth Connect 2.1.0 or greater
    1. Follow any guidelines from Mirth Connect Downloads for install
    2. We find that you either use a GUI installer download or simply unzip a file to install.
      • For example: tar -xzf mirthconnect-2.1.0.5374.b644-unix.tar.gz -C /nhin/mirthconnect
      • This would make your MIRTH_HOME be /nhin/mirthconnect/Mirth\ Connect
    3. (Optional) Install the Mirth Connect Command Line Interface

Configure Mirth Connect

  1. Log-in as the root user (or Administrator if Windows).
  2. Ports must be accessible through any firewall on the system. The default ports for Mirth Connect are listed here. Firewall settings may need to be made now. If these are in use then you will need to change that here and in the Mirth Connect properties (subsequent step).
    • 8080
    • 8443
    • 1099
  3. Add the following directories to Mirth Connect home:
    • /nhin/mirthconnect/HL7OutputMessage
    • /nhin/mirthconnect/HL7LabOutputMessage
    • /nhin/mirthconnect/HL7MedOutputMessage
    • /nhin/mirthconnect/HL7DXOutputMessage
    • /nhin/mirthconnect/HL7OtherOutputMessage
    • /nhin/mirthconnect/HL7ReceiveProcessedMessage
    • /nhin/mirthconnect/HL7ReceiveErrorMessage
  4. Change permissions on these directories
    • chmod 774 /nhin/mirthconnect/HL7OutputMessage
    • chmod 774 /nhin/mirthconnect/HL7LabOutputMessage
    • chmod 774 /nhin/mirthconnect/HL7MedOutputMessage
    • chmod 774 /nhin/mirthconnect/HL7DXOutputMessage
    • chmod 774 /nhin/mirthconnect/HL7OtherOutputMessage
    • chmod 774 /nhin/mirthconnect/HL7ReceiveProcessedMessage
    • chmod 774 /nhin/mirthconnect/HL7ReceiveErrorMessage
  5. (Optional) Change Mirth Connect to use port 7080 if your system already uses port 8080 (the default).
    1. edit /nhin/mirthconnect/Mirth\ Connect/conf/mirth.properties (Note the space in the name "Mirth Connect" where the "\" escapes the space character.)
    2. change field http.port to be 7080
  6. Install JAXWS libraries so that MirthConnect can use them.
    1. URL to retrieve the JAXWS libraries: http://jax-ws.java.net/ - Version 2.2.1
      1. This file has already been included in the artifacts above.
      2. Unzip JAXWS2.2.1-20100617.zip and copy all of its contents to /nhin/mirthconnect/Mirth\ Connect/custom-lib
  7. Start MirthConnect
    1. Navigate to /nhin/mirthconnect/Mirth\ Connect
    2. Run mcserver
      1. sudo ./mcserver
    3. Note: This will run MirthConnect.
  8. Run MirthConnect Administrator
    1. Run FireFox on the host server where Data Normalization is installed not from a remote machine.
    2. Go to URL: http://localhost:8080 Modify if you changed the default ports.
    3. Click on "Launch Mirth Connect Administrator"
      1. Select "Open With", browse to <JAVA_HOME>/bin/javaws, and select Open.
      2. Select Do this automatically for files like this and click OK.
      3. Select Run to launch Mirth Connect Administrator.
    4. Login
      1. User: admin
      2. Password: admin
      3. On the first time it may give you a Welcome to Mirth Connect screen. If so:
        1. Keep the user name and password the same.
        2. Fill in required fields (optional fields if desired).
        3. Uncheck the Register and Submit usage statistics checkboxes.
        4. Select Finish.
  9. Import the HL7 message receiver and separator channel: (HL7ReceiveMessageSeperatorChannel.xml)
    1. From the MirthConnectAdministrator, click on "Channels".
    2. Click on the "Import Channel" link under "Channel Tasks".
    3. Navigate to where you placed the artifacts, perhaps /nhin/mirthconnect.
    4. Select the "HL7ReceiveMessageSeperatorChannel.xml" file, followed by "Open".
    5. You will be in edit mode. Click on the "Save Changes" link under "Channel Tasks".
    6. You should now see a channel called "HL7ReceiveMessageSeperator" in the list of Channels within the MirthConnect Administrator.
  10. Deploy the HL7 message receiver and separator channel
    1. Click on the "Channels" link to show the channels.
    2. Right-click on the "HL7ReceiveMessageSeperator" and select "Deploy Channel".
    3. You will be switched to the Dashboard where you can see the results of any processing by the channels.

Install MySQL

Note that another DBMS could be used but you would need to extrapolate from these instructions.

  1. Install MySQL 5.1 or greater

Configure MySQL

The 4 Channels and 1 DB Creation Script are intended for deployment at a receiving location that intends to receive CEM XML Result Messages from UIMA (Lab, Meds, AdminDX, or Patient CEMs) and store the results in the MySQL CEM Database. Steps are based on these: SHARP_SECUSE_DB_AND_STORAGE_CHANNELS_INSTALL.pdf

  1. Ports must be accessible through any firewall on the system. The default ports for MySQL are listed here. Firewall settings may need to be made now. This would only be if you want to administer this DB from a remote system. The Data Normalization pipeline does not need this open as it runs together on the local system.
    • 3306
  2. Run the configuration script.
    1. MySQL statements to create the SHARPn database is in the file Mydb_ddl_v2.2.sql. Chose one of the ways to execute it.
    2. Using the root MySQL user, open and run the script through the MySQL SQL editor or from the mysql command line, for example
      • mysql --user=root --password=sharpn < /nhin/mirthconnect/Mydb_ddl_v2.2.sql
  3. Add the following directories to Mirth Connect home:
    • /nhin/mirthconnect/secUsePatientInputMessage
    • /nhin/mirthconnect/secUsePatientErrorMessage
    • /nhin/mirthconnect/secUsePatientProcessedMessage
    • /nhin/mirthconnect/secUseNotedDrugInputMessage
    • /nhin/mirthconnect/secUseNotedDrugErrorMessage
    • /nhin/mirthconnect/secUseNotedDrugProcessedMessage
    • /nhin/mirthconnect/secUseLabInputMessage
    • /nhin/mirthconnect/secUseLabErrorMessage
    • /nhin/mirthconnect/secUseLabProcessedMessage
    • /nhin/mirthconnect/secUseAdminDXInputMessage
    • /nhin/mirthconnect/secUseAdminDXErrorMessage
    • /nhin/mirthconnect/secUseAdminDXProcessedMessage
  4. Change permissions on these directories
    • chmod 774 /nhin/mirthconnect/secUsePatientInputMessage
    • chmod 774 /nhin/mirthconnect/secUsePatientErrorMessage
    • chmod 774 /nhin/mirthconnect/secUsePatientProcessedMessage
    • chmod 774 /nhin/mirthconnect/secUseNotedDrugInputMessage
    • chmod 774 /nhin/mirthconnect/secUseNotedDrugErrorMessage
    • chmod 774 /nhin/mirthconnect/secUseNotedDrugProcessedMessage
    • chmod 774 /nhin/mirthconnect/secUseLabInputMessage
    • chmod 774 /nhin/mirthconnect/secUseLabErrorMessage
    • chmod 774 /nhin/mirthconnect/secUseLabProcessedMessage
    • chmod 774 /nhin/mirthconnect/secUseAdminDXInputMessage
    • chmod 774 /nhin/mirthconnect/secUseAdminDXErrorMessage
    • chmod 774 /nhin/mirthconnect/secUseAdminDXProcessedMessage
  5. Add the Channel Configuration(s) for converting CEM results to another form
    1. Run the Mirth Connect Administrator, as when you installed Mirth, and log-in as admin.
    2. Import each of the CEM to Database channels: (CemSecUsePatientToDatabaseChannel.xml, CemSecUseNotedDrugToDatabaseChannel.xml,CemSecUseLabToDatabaseChannel.xml,CemSecUseAdminDXToDatabaseChannel.xml)
      1. From the MirthConnectAdministrator, click on "Channels".
      2. Click on the "Import Channel" link under "Channel Tasks".
      3. Navigate to where you placed the artifacts, perhaps /nhin/mirthconnect.
      4. Select each XML file, followed by "Open".
      5. You will be in edit mode. Click on the "Save Changes" link under "Channel Tasks".
      6. You should now see all the CEM to Database channels within the MirthConnect Administrator.

Install UIMA-AS

Unstructured Information Management Architecture - Asynchronous Scaleout is used as a required component of the Data Normalization pipeline. Mirth Connect will be configured to include a plug-in and connector that takes advantage of UIMA-AS. UIMA-AS includes UIMA and the Apache ActiveMQ implementation of JMS.

  1. Install UIMA-AS 2.3.1 or greater
    1. Follow any guidelines from Apache UIMA
    2. You can also use the UIMA README for help
    3. Make sure you select the files for UIMA-AS not UIMA

Configure UIMA-AS

  1. The UIMA instructions are not explicit about what environment variables need to be set
    1. Set JAVA_HOME to the directory of your JRE installation you would like to use for UIMA.
    2. Set UIMA_HOME to the apache-uima directory of your unpacked Apache UIMA distribution
      • For example, export UIMA_HOME=/usr/local/uima-as/apache-uima-as-2.3.1
    3. Append UIMA_HOME/bin to your PATH
      • For example, export PATH=$PATH:/usr/local/uima-as/apache-uima-as-2.3.1/bin
  2. Copy the UIMA JAR files to the Mirth Connect lib for its use as a Java library
    1. From UIMA_HOME/lib to MIRTH_HOME/lib
      • uimaj-as-core.jar
      • uimaj-as-jms.jar
      • uima-core.jar
      • uimaj-as-activemq.jar
  3. Copy the Active MQ JAR files to the Mirth Connect lib for its use as a Java library
    1. From UIMA_HOME/apache-activemq-5.4.1/lib to MIRTH_HOME/lib
      • activemq-core-5.4.2.jar
  4. Starting the ActiveMQ Broker
    1. Change to the UIMA_HOME/bin directory
    2. Start the Active MQ broker, for example:
      • sudo ./startBroker.sh
  5. Add UIMA capability to Mirth Connect (plugin and connector)
    1. (Optional) Examples of UIMA and Mirth Integration
    2. Steps are base on these Mirth UIMA install instructions.
    3. Install the UIMA Plugin Mirth Connect extension
      • Click on the "Extensions" link to show the extensions.
      • Navigate to where you placed the artifacts, perhaps /nhin/mirthconnect.
      • Select the "Uimaservice-2.1.0.b662.zip" file, followed by "Open" and "Install".
      • Restart the Mirth Connect server which also means the Mirth Connect Administrator.
    4. Install the UIMA Sender Mirth Connect Connector
      • Click on the "Extensions" link to show the extensions.
      • Navigate to where you placed the artifacts, perhaps /nhin/mirthconnect.
      • Select the "uima-2.1.0.b662_modified.zip" file, followed by "Open" and "Install".
      • Restart the Mirth Connect server which also means the Mirth Connect Administrator.

Testing

    1. Use the file TestHL7Med1.txt to test the pipeline.
    2. The name of the file must end in ".txt". When the channel was configured, it was configured to look for files with that ending.
    3. Copy the file to: /nhin/mirthconnect/HL7OutputMessage
      • cp /nhin/mirthconnect/TestHL7Med1.txt /nhin/mirthconnect/HL7OutputMessage/
      • Watch the Mirth Connect dashboard for a report of the file being processed.

The completely automated, end-to-end process for documents flowing through the pipeline was not realized in version 1.0.

Next Steps

If you have not done so already you must look at the pipeline configuration. The default pipeline will not likely meet your needs.