Importing HL7 Labs

Labwork can be pushed into OSCAR with the HL7 transport utility from a Windows workstation. Use similar instructions to install on a Linux machine.

Preface

This utility as installed on the Windows workstation that downloads the labwork will transfer the files automatically to the OSCAR server using Secure Socket Layer technology. 

Document Version History

• v1.0 – Initial public release to oscarmanual.org – Jan 12, 2016
• v1.1 – Initial OSCAR 15 release – Mar 5, 2016
  
  

 copyright © 2016 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

Prerequisites

It is assumed that

1. You have the time.  Allow for about 2 hours.
2. You have the skills.  Comfort using a Windows Command line is essential.  Familiarity dealing with source code and Java build tools helps.
3. You have administrator access to a windows server or workstation that will be downloading the labs.  This machine is typically in the front office on the local network, but can be anywhere that has internet access to the OSCAR server and the the laboratories.

Installing The Infrastructure Packages

Java

Oscar works the best with Oracle-Sun-Java.  The version below has been tested, you can use a newer one, just ensure that it is the same type.  The wrapper that starts this Mule needs a 32 bit Java.

Use your webbrowser to accept Oracle's terms and download from Oracle the 32bit Windows Java JDK installer.  The following example uses the file pattern for 32 bit Oracle Sun Java 8 update 66.

jdk-8u66-windows-i586.exe

The typical windows installation process will place the executable files in c:\Program Files (x86)\Java\jdk1.8.0_66\jre .

Maven

Maven is tool that you will use to compile a java JAR file configured for your system.  Download the latest maven from apache.  It will be in a bin tar which you need to extract using either a command line tool such as TarTool or a GUI extractor such as 7-zip. Extract to an appropriate location such as Program Files.

TarTool apache-maven-3.3.9-bin.tar.gz "C:\Program Files\maven-3.3.9"

The maven package is thus extracted into a subdirectory

Git

Git is a software configuration management (SCM) tool that you can use to retrieve the source files for this program from the repository

You can download either the 32bit or 64bit installer from https://git-scm.com/download/win

Then use Git to clone the source files into an appropriate location.

mkdir C:\home
cd C:\home
git clone git://git.code.sf.net/p/oscarmcmaster/hl7_file_management oscarmcmaster-hl7_file_management

Configuration of Packages

Environmental Variables

You should set some system variables so that Windows knows where to find the various components

1. Open the 'System' control in the 'Control Panel'
2. Under the 'Advanced' tab click the 'Environment Variables' button
3. In the 'System variables' window click the 'New...' button
1. Variable Name: MULE_HOME
2. Variable Value: C:\home\oscarmcmaster-hl7_file_management\mule-1.3.3
3. Click 'OK'
4. In the 'System variables' window click the 'New...' button
1. Variable Name: MAVEN_HOME
2. Variable Value: C:\Program Files\maven-3.3.9
3. Click 'OK'
5. In the 'System variables' window highlight the 'Path' variable and click the 'Edit...' button
1. add ';%MULE_HOME%\bin;%MAVEN_HOME%\bin' to the end of the 'Variable Value'
2. Click 'OK'
6. Click 'OK'

OSCAR Keys

Log into the OSCAR server and click the admin tab at the top right. Scroll to the bottom of the Administrative Page and click on the
Key Pair Generator link.

1. Input 'oscar' without the quotes as the service name and press the 'Create Key Pair' button. If you received the error:  "Failed: The oscar key pair has already been created" It is ok to ignore it.
2. Input your service as the service name and select the message type from the drop down menu and click the 'Create Key Pair' button. A window will pop up asking you to save 'keyPair.key'.  Remember the location where you saved it.

If you wish to use multiple message formats such as MDS (Lifelabs) and CML you will need  a different keypair for each message format.

Configure Properties File

Edit the file 'LabProperties.properties' in the 'src/main/resources' directory to use your own directories. If the directories do not exist they will be created at runtime. Also make sure to include the address of the OSCAR server and the location of 'keyPair.key' that you saved in the previous step.  Instructions are included at the top of the file, example settings are listed below.  Note the UNIX style c:/ for directory

example settings for a windows system downloading from Lifelabs(MDS) and CML

incomingHL7dir1    = c:/DATA/incomingHL7dir
incomingHL7dir2    = c:/DATA/LIFELABS
incomingHL7dir3    =  
errorHL7dir    = c:/messages/errorHL7dir
completedHL7dir    = c:/messages/completedHL7dir

keyLocation1     = c:/messages/keyPair_oscar_peter_CML.key
keyLocation2     = c:/messages/keyPair_lifelabs.key 
keyLocation3     =  

oscarURL     = https://10.69.241.15:8443/oscar

 (the SMPT settings are optional)

Configure Config File

Depending on how many different message formats you wish to use you will have to use a different config file.   If you are downloading just one lab then you can leave mule-config.xml as is.  Otherwise use the template for the number of message formats (eg mule-config_two-formats.xml for when you are downloading from Lifelabs and CML), and save to 'src/main/resources/mule-config.xml'.  You will not usually need to edit the source template.

Build the Package

Open the command line by selecting 'Run...' from the start menu and typing in 'cmd' and clicking 'OK'

Navigate to the 'oscarmcmaster-hl7_file_management' directory within the command line.

Set JAVA_HOME to point to the JDK using the following command ( be sure the directory is correct ):

set JAVA_HOME=c:\Program Files (x86)\Java\jdk1.8.0_66\jre

Use maven to build the source:

mvn package

copy the resultant jar to the mule library (the existing jar in source needs to be overwritten):

copy target/IncomingHL7Management-1.0-SNAPSHOT.jar mule-1.3.3/lib/user/IncomingHL7Management-1.0-SNAPSHOT.jar

Leave the command line open for the next step.

Start Mule

Type the following into the command line:

mule install

Mule is now installed as a windows service, it will start when windows boots. It can be started or stopped using the following commands:

mule start
mule stop

Mule can be removed from being a service with the following command:

mule remove