Getting Started with the Integrator

Introduction

The Integrator is a software component which allows n OSCAR instances to share records. It primarily acts as a data cache, stores linking information, and allows other software to query it (OSCAR).

Architecture

Setup

You will need to have the integrator running on it's own JVM from any OSCAR. Here are the basic steps

Note that this document reflects the new way of doing things, so grab the integrator code this way. 

Getting the code

The code is housed in a GIT repository. You should have git, if not, add it using apt-get install git

git clone git@bitbucket.org:oscaremr/integrator.git

git checkout OSCAREMR-6112-change-integrator-job-to-w

Preparing to build

Update src/main/resources/config.xml or create a copy of it and use that as the override file. You should update the database username, password, and uri at the very least. Make sure the paths exists and the defaults make sense for you.

Create an empty database and grant access to your user/password.

Build

The integrator is built using Apache Maven

mvn package

You should have a successful build, giving you a WAR file, and updating your catalina_base subdirectory with a ready to go tomcat base directory.

Start server

update your set_env.sh file and then source it, and start up tomcat

source set_env.sh

$CATALINA_HOME/bin/startup.sh

Configure

Go to http://localhost:8085/caisi_integrator/site/ (or wherever you installed it) and login using admin/password

to to administration, and facilities

Add a Facility for each of your OSCAR instances

Part 2 - Setting up an OSCAR instance to send data to the integrator

OSCAR must be configured to be able to "talk" to the integrator, Communication happens in 2 distinct ways

1. Files are generated on a scheduled basis which are then loaded into the integrator.
2. Real time web services are called on the integrator to request data for viewing.

We're going to focus on sending the data to the integrator in this section.

You will need to start up OSCAR with the following System property org.apache.cxf.stax.allowInsecureParser=1. The easiest way to pass this into TOMCAT is to add

-Dorg.apache.cxf.stax.allowInsecureParser=1 

to your $CATALINA_OPTS environment variable.

Startup OSCAR next and login. Go to the Administration Panel,and under the section System Settings, choose Manage Facilities, and Edit.

You will need to check off Enable Integrator, set the URL (see example and adjust hostname/port if necessary), username/password.

There are also some configuration in the properties file. You will probably not want all of the defaults.

# Type of shared issues between facilities, through Integrator
COMMUNITY_ISSUE_CODETYPE=icd10

# integerator update period in milliseconds
INTEGRATOR_UPDATE_PERIOD=120000

# switch to force a full update
INTEGRATOR_FORCE_FULL=no

 #set false if you only have 1 facility on this instance..a bit of an optimization.
INTEGRATOR_LIMIT_TO_FACILITY=false

# Has to be enabled for Ontario MD funded sites. This will autoselect primaryEMR to yes if roster_Status = RO
#FORCED_ROSTER_INTEGRATOR_LOCAL_STORE=yes

#Integrator update thread runs as this oscar user. use the providerNo. No entry means -1 or system,system.
#INTEGRATOR_USER=

#-1 will disable it. Disabled by default
seconds_till_considered_stale=-1

integrator.send.issues.disabled=false
integrator.send.preventions.disabled=false
integrator.send.notes.disabled=false
integrator.send.drugs.disabled=false
integrator.send.admissions.disabled=false
integrator.send.appointments.disabled=false
integrator.send.measurements.disabled=false
integrator.send.measurementExts.disabled=false
integrator.send.measurementTypes.disabled=false
integrator.send.measurementMaps.disabled=false
integrator.send.dx.disabled=false
integrator.send.billing.disabled=false
integrator.send.eforms.disabled=false
integrator.send.eform_values.disabled=false
integrator.send.allergies.disabled=false
integrator.send.documents.disabled=false
integrator.send.forms.disabled=false
integrator.send.labs.disabled=false

#INTEGRATOR_OUTPUT_DIR=

When the task runs (using INTEGRATOR_UPDATE_PERIOD to determine how often), ZIP files are created in INTEGRATOR_OUTPUT_DIR which will then be loaded into the integrator. 

The build_doc_zip.sh script file will be invoked (it should be in the INTEGRATOR_OUTPUT_DIR folder). This script is written for a linux system and requires sed and zip binaries. It simply will create a <filename>-Docs.zip file which contains all the documents referenced in the export. you will want to set the BASE_DIR variable in the script. The script was originally written where INTEGRATOR_OUTPUT_DIR = DOCUMENT_DIR, so if that's not your case, this script may need to be slightly altered.

Putting it all together

So now you have an installed and configured integrator and have 1..n OSCAR instances creating <filename>.zip and <filename>-Docs.zip files, how does it all work?

Depending on how you are deploying this (multiple servers, etc) you just need a script on a cron to move the zip files from INTEGRATOR_OUTPUT_DIR directories to the integrator's server/import/scanDirectory (config.xml or override file).

The integrator will read files from any OSCAR system,  check dependencies, etc and proceed to import.