Mule to Upload Labs

UpdatedSeptember 23, 2024

By Peter Hutten-CzapskiPeter Hutten-Czapski

Preface

These are instructions on how to set up automated uploads of lab files to OSCAR.

Document Version History

v1.0 – Initial public release to oscarmanual.org – Jan 12, 2016
v1.1 – Initial OSCAR 15 release – Mar 5, 2016
v2.2 – Updated and documented Linux and Excelleris approach – Aug 2, 2024

Prerequisites

You are familiar with the Command line, dealing with source code and Java build tools.
We recommend a dedicated machine (it can be a Virtual Machine) that can stay on 24/7 that is separate from OSCAR and is compatible with 32bit Java. (here we suggest Linux Mint 21)
You have labs configured to be downloaded to the server

Installing Mule Uploader to EMR

Manual Uploads

You can take HL7 lab files and manually upload them in to your OSCAR EMR via “InBox -> HL7 Lab Upload” but this utility is mostly for testing. If any issues arise edit the oscar.properties files to enable processing and display the type of labs.

To manually upload select the correct Lab type depending on which lab vendor the file is from, choose the file and click the [upload] button. Some common labs are

ALPHA is AlphaLabs
GDML is Dynacare
MDS/LifeLabs is LifeLabs (old format)
Excelleris(ON) is LifeLabs Excelleris (new)
EXCELLERIS is LifeLabs Excelleris BC

Mule can automatically take the HL7 files in a specific directory and upload it to your EMR. It comes with error handling and messaging and will store a copy of your uploaded files just in case. When you get files it will push them to OSCAR.

While we recommend Linux Mint to run Mule, the utility also runs on Windows. Which system you install on really depends on what is the most convenient location for the downloaded files. If the scripts are Linux scripts use Mint please. If you have a proprietary downloader that requires Windows then installing Mule on Windows makes more sense. Instructions for both follow. Neither Ubuntu nor MacOS are currently suitable due to Java requirements (see below).

Installing the Infrastructure Packages

Java

This Mule is very ornery, follow these instructions carefully.

Despite the theory that Java runs everywhere independent of operating system or chip on the motherboard, that is not quite true, and proven not to be true for our purposes. Thus the Java you have installed on your system is very likely NOT the Java you will be using. The version below has been tested, you can use a newer one, just ensure that it 32 bit. It is futile trying to build or run using the 64 bit version.

For Linux this means Debian or Mint (tested on Mint 21.1) especially if you have other Java’s (64 bit) installed.

Recent Windows machines have not been tested, however if you can install the 32bit MSI Java installer you should be fine. In a pinch try Windows 10.

The following example uses the file pattern for openlogic openjdk Java 8 update 422 from https://www.openlogic.com/openjdk-downloads. Other sources of 32 bit openjdk Java may be appropriate but have not been tested.

openlogic-openjdk-8u422-b05-windows-x32.msi

openlogic-openjdk-8u422-b05-linux-x32-deb.deb

The typical windows installation process will place the executable files in c:\Program Files (x86)\Java\jdk1.8.0_422\jdk or similar

Note that the wrapper that starts this Mule needs a 32 bit Java. For Linux even if you have JAVA_HOME set to 32 bit, you still have to point the Java

sudo update-alternatives --config java

to the 32 bit Java for Mule to run or it panics. Of course you can run other Javas for other applications. For OSCAR this would require you to set your JAVA_HOME preference in /etc/default/tomcat9 to your other Java.

Maven

Maven is tool that you will use to compile a java JAR file configured for your system. For Windows 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.

For linux you can 
sudo apt install maven

Git (or get the source as a zip)

Git is a software configuration management (SCM) tool that you can use to retrieve the source files for this program from the repository. If you prefer you can skip installing git and just download the source as a zip

For linux Ubuntu sudo apt install git. For windows 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. For windows use C:\home

mkdir C:\home
cd C:\home
git clone git://git.code.sf.net/p/oscarmcmaster/hl7_file_management hl7_file_management
// OR if you have bitbucket credentials
git clone git@bitbucket.org:oscaremr/hl7_file_management.git

OSCAR Keys

For OSCAR to accept uploads from Mule, keypairs have to be configured to authenticate the transfer. Log into the OSCAR server and click the admin tab at the top right. Scroll to the bottom of the System Management menu, open it and click on the Key Pair Generator link to open the Key Manager

Click on Create New Key. If you don’t have a “OSCAR public key” visible (as above) then input ‘oscar’ without the quotes as the service name, 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.

If you have already an OSCAR public key then you need to generate a private key for each lab type. Click on the Create New Key and then provide the service name and Lab type for each of the lab types you need to import.

The Oscar key is one shared key which authenticates who the server is to other people, that’s why there’s only one Oscar key (Oscar server is always the legitimate server to everyone). The “private keys” are service keys, which are keys specific to each service. So if you need 5 different lab services you have 5 different service keys so you can control access to each service individually (ex. disable a single connection).

If you need to delete any key (this should not be done lightly), they are stored in the publicKeys table. The OSCAR Key is stored in oscarKeys

Remember the location where you saved it. (ie. “C:\home\oscar-keypairs\keyPairGdml.key”)

Do not copy and paste the key contents, especially in Windows, as you will probably run into issues with line feeds.

Setup Directories

Directories need to be setup for all the other files. Make a directory for each of the lab types you will be downloading. The example shows 3 lab types but 1-3 labs will be fine. Here we are setting up the old MDS/Lifelabs, Excelleris and POI (in practice its usually MDS or Excelleris). Any names will do but should be adjusted for your purposes to make it easy to debug.

~$ mkdir HL7Data
~$ cd HL7Data
~/HL7Data$ mkdir incomingEXCELLERISdir 
~/HL7Data$ mkdir incomingPOIdir
~/HL7Data$ mkdir incomingMDSdir 
~/HL7Data$ mkdir completedHL7dir 
~/HL7Data$ mkdir errorHL7dir 
~/HL7Data$ mkdir keys

Copy your keypair(s) to the keys directory

Configure Properties File

Edit the file ‘LabProperties.properties’ in the ‘~/hl7_file_management/src/main/resources’ directory to use your own directories that you created in the previous step. Note the UNIX style forward slash usage “c:/” for directory paths even for Windows. The directories you specify will be created at runtime if they don’t exist. 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. The smpt settings are optional but put something there in case you want to implement it later.

Example settings for a Linux system downloading from three Labs

incomingHL7dir1 = home/peter/HL7Data/incomingEXCELLERISdir
incomingHL7dir2 = home/peter/HL7Data/incomingPOIdir
incomingHL7dir3 = home/peter/HL7Data/incomingMDSdir
errorHL7dir = home/peter/HL7Data/errorHL7dir
completedHL7dir = home/peter/HL7Data/completedHL7dir

keyLocation1 = home/peter/HL7Data/keys/keyPairExcelleris.key
keyLocation2 = home/peter/HL7Data/keys/keyPairPOI.key
keyLocation3 = home/peter/HL7Data/keys/keyPairMDS.key

oscarURL = https://your.oscaremr.org:8443/oscar

# smtpServer for notifying errors
smtpServer = localhost:25
senderEmailAddress = labupload@yourdomain.com
recipientEmailAddress = username@email.com

For Windows use Linux style paths prefixed with the drive eg for two labs

incomingHL7dir1 = c:/DATA/LIFELABS
incomingHL7dir2 = c:/DATA/GDML

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 Dynacare), and save to ‘src/main/resources/mule-config.xml’. You will not usually need to edit the source template unless you need to download more than 3 lab types.

WINDOWS (linux follows)

Environmental Variables WINDOWS

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

Open the ‘System’ control in the ‘Control Panel’
Under the ‘Advanced’ tab click the ‘Environment Variables’ button
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’
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’
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’
Click ‘OK’

Build the Package Windows

For windows open the command line by selecting ‘Run…’ from the start menu and typing in ‘cmd’ and clicking ‘OK’

In any system navigate to the ‘oscarmcmaster-hl7_file_management’ directory within the command line.

For Windows 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_422\jdk

Use maven to build the source:

mvn package

Wait until you get “BUILD SUCCESS” and 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.

Install and Start Mule Windows

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

If you want to add another lab or change the config file, remember to stop Mule, remove Mule as a service; delete the target jar and then go back to editing the properties file, generating the Java package, and reinstalling the updated Mule.

mule stop
mule remove

Linux Instructions

Build the Package Linux

Navigate to the ‘hl7_file_management’ (or similar) directory within the command line.

For Linux set JAVA_HOME to point to the JDK using the following command ( be sure the directory is correct for your system ) as ROOT user:

export JAVA_HOME=/usr/lib/jvm/openlogic-openjdk-8-hotspot-i386
sudo export MULE_HOME=/home/peter/hl7_file_management/mule-1.3.3

Type the following into the command line:

cd /home/peter/hl7_file_management/utils
./install.sh

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

/etc/init.d/muled start
/etc/init.d/muled stop

If you want to add another lab or change the config file, remember to stop Mule, remove Mule as a service; and then go back to editing the properties file, generating the Java package, and reinstalling the updated Mule.

sudo ./uninstall.sh

Other Notes

Original instruction for Importing HL7 Labs by Peter Hutten-Czapski initially posted to oscarmanual.org
Supplementary instructions from Marc Dumontier that might be helpful for Linux as well.

Troubleshooting

Exception in thread "main" java.lang.IllegalArgumentException: PANIC: Mule has been started with an unsupported classloader: 
jdk.internal.loader.ClassLoaders$AppClassLoader.

It means that the wrapper picked up the 64 bit java distribution while trying to start. To fix

sudo update-alternatives --config java

and pick the 32 bit Java version to provide /usr/bin/java

If OSCAR is not accepting the connection examine the key pair file for inadvertent line feeds. The keypair file saved may contain line feeds code (hidden CR/LF) within the hash which must be removed for Mule to read the keys correctly. In other words, you need to delete the hidden return/line feed that separates each line of the key so that the key is on one single line with no word wrap. Use an editor such as Notepad++ to edit the keyfile that can show hidden line feeds and save in Linux format

Credits

Dr. Peter Hutten-Czapski
Marc Dumontier
Dr. Kevin Lai
Dr. Ian Pun