How Integrator works

Both Oscar sites periodically push data into Integrator, which stores it into its database.
Patients have their demographics registered in both Oscar sites and "linked" through Integrator.
When a patient's chart is opened in one Oscar site, Oscar will contact the integrator and pull his/her chart data from the other site(s).
Chart data from remote site is shown with special indication.

Prerequisites

Java version: openjdk-6

(linux command) sudo apt-get install openjdk-6-jre

Tomcat version: tomcat6

(linux command) sudo apt-get install tomcat6

Tomcat setting

The following line should be added to tomcat start script at before executing the web service:

export JAVA_OPTS="-Xmx1024M -Dcaisi_integrator_config=/usr/share/tomcat6/integrator_override.xml"

Notes:

1) -Xmx1024M is a suggested value. More memory can be assigned if available.

2) /usr/share/tomcat6/ is a suggested path and can be changed.

Oscar version

Integrator works with Oscar release 12.1

Installation Via Script

We have created a script which will:

create integrator_override.xml
prepare the caisi_integrator database
download caisi_integrator.war file

It can be downloaded here: integrator_install.sh

Before running, edit the script and set the following variables:

Variable in script	Value
USER=	the mysql username you would like to use to access the database
PASSWORD=	the password you would like to use to access the database
DB_HOST=	127.0.0.1
DB_PORT=	3306
DATABASE_NAME=	caisi_integrator
INTEGRATOR_HOST=	the external IP/hostname used to access the server
INTEGRATOR_PORT=	the external port used to access the server

After running, move override file and the war file to their directories:

cp integrator_override.xml /usr/share/tomcat6/

cp caisi_integrator.war /var/lib/tomcat6/webapps/

Skip to oscar.properties and proceed from there.

Manual Setup for Oscar/Integrator

Get Integrator

Option 1: Get war file

You can always download the latest WAR file for the integrator from this url: https://demo.oscarmcmaster.org:11042/job/integratorMaster/lastBuild/org.oscarehr$caisi_integrator/artifact/org.oscarehr/caisi_integrator/0.0-SNAPSHOT/caisi_integrator-0.0-SNAPSHOT.war

Option 2: Get source and build war file

Enter in Command Line:

git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/integrator
cd integrator
mvn clean package

After the integrator is built, the war file will be stored in integrator/target/

integrator_override.xml

This file makes 2 main settings on Integrator:

1) database info for Integrator

2) url for Oscar sites to access Integrator <https_endpoint_url_base>

In order for this file to function please refer to section - Tomcat setting

If this file does not exist/function Integrator runs with the default values (<<tomcat_base>>/webapps/caisi_integrator/WEB-INF/classes/config.xml)

Example integrator-override.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<server>
		<database>
			<user>root</user>
			<password>rootpass</password>
			<url_prefix>jdbc:mysql://10.10.10.1:3306/</url_prefix>
			<schema>caisi_integrator</schema>
			<driver>com.mysql.jdbc.Driver</driver>
		</database>
		<integrator_server>
			<https_endpoint_url_base>http://oscarintegrator:8080/caisi_integrator/ws</https_endpoint_url_base>
			<require_consent_to_read_data>false</require_consent_to_read_data>
			<require_phi_filter_to_read_data>false</require_phi_filter_to_read_data>
			<log_performance>false</log_performance>
		</integrator_server>
	</server>

<require_consent_to_read_data>, <require_phi_filter_to_read_data>, and <log_performance> should all be set to false unless necessary.

Integrator war file

Rename the above acquired war file to "caisi_integrator.war"
If you are running integrator in a dedicated server, put the war file into /var/lib/tomcat6/webapps/ If you are running integrator alongside with Oscar, put the war file together with the Oscar war file.

Integrator database setup

get sql script from https://demo.oscarmcmaster.org:11042/job/integratorMaster/lastBuild/artifact/target/create_tables.sql
create database:
(linux commands)
create database caisi_integrator | mysql -uroot -prootpass -h10.10.10.1 -P3306
grant all on caisi_integrator.* to root@localhost identified by "rootpass" | mysql -uroot -prootpass -h10.10.10.1 -P3306 caisi_integrator
Note:
The above commands are only an example. All the databases, users, passwords, hosts, ports can be changed but keep them consistent along all setup. Same thing apply to the following steps.
build database:
(linux command) mysql -uroot -prootpass -h10.10.10.1 -P3306 caisi_integrator < create_tables.sql
prepare initial data:
Login to mysql and use the caisi_integrator database. Run the following commands:
insert into SiteUser (name,password) values ('admin',unhex(sha1('admin')));
create table CachedProviderRole (caisiItemId varchar(16) not null, integratorFacilityId int(11) not null, providerRole varchar(32) not null);
create table HomelessPopulationReportPrograms (configurationTime datetime not null, index(configurationTime), facilityId int not null, programId int not null);

oscar.properties

Ensure these three properties are present in the oscar.properties file for each Oscar system you wish to connect to the integrator:

Variable	Value	Comment
program=	on
INTEGRATOR_UPDATE_PERIOD=	1800000	This value is in milliseconds. OMD requires sync within 30 minutes.
ENABLE_CONFORMANCE_ONLY_FEATURES=	true

You must restart Oscar in order for changes to the oscar.properties file to take effect.

Web Setup

Integrator Web Setup

Run Integrator by starting tomcat
Open a web browser and go to: http://integrator_server_name:8080/caisi_integrator

change "integrator_server_name" and port according to your own settings
Select "Integrator Site"
Login as "admin", password: "admin"
Select "Administration"
Select "Manage Facilities"
Select "Add New Facility", enter a username and password for each Oscar site to use on connecting to the integrator. The facility username and password will be used in the next section.
Repeat step 7. Each facility represents one Oscar site.

Oscar Web Setup

Start Oscar (if not already running)
Login to Oscar using an account with admin rights
Select "Admin" in the top menu
Select "Manage Facilities" under "Misc"
Select "Edit"
Change "Name", "Description" to something of your choice.

The name field will be used to identify this Oscar instance at other facilities so we suggest using something short and identifiable.
For example, a name of "Fakestreet Family Health Team" is likely too long, whereas "FFHT" may not be unique or identifiable, but "Fakestreet" allows users at other sites to know what site information is coming from.
Enter "http://integrator_server_name:8080/caisi_integrator/ws" into "Integrator Url" (This should be the URL from step 2 in the previous section + "/ws")
Enter "Integrator User" and "Integrator password" with the facility name and password from step 7 in the previous section
Check "Enable Integrator"
Save. You will be prompted with "Remove Demographic Identity NOT checked! Is it OK?". Select "OK".

Repeat the above steps for each Oscar site you wish to connect to the integrator. Each site must have a different facility name.

Oscar will now push data to Integrator once every INTEGRATOR_UPDATE_PERIOD. Note that the update period starts its count on Oscar startup, so you may not see any data push immediately after the above setup.

A patients E-Chart Encounter notes do not abide by the syncing period set by 'INTEGRATOR_UPDATE_PERIOD'. Encounter notes update 60 minutes after the previous Encounter notes sync.

Integrator Preferences Within Oscar

The purpose of setting this is to allow all patients to be synced, or by default only Rostered patients will be synced.

Login Oscar with an account which has admin rights
Select "Admin" in the top menu
Select "Integrator Preferences"
Check "All Patients with Charts Opened Since [never]" and save.

Note:

1) To change the [never] in step 4), login mysql and use the Oscar database, run the following command:

insert into property (name, value) values ("integrator_last_push", "2012-06-14 17:03:30");

* Change the date and time according to your need

2) On 1st push/pull of data to Integrator, Integrator Preference may be reset. Please re-apply the setting if this happens. (Bug to be fixed)

Adding a "Linked" Patient

Do NOT create the same patient demographic in different Oscar sites. The "linking" does not work this way.

Assume you have a patient named "Linker, Boy" in Oscar site 1. Follow the steps below to create his "linked" counterpart in Oscar site 2:

Wait until Oscar site 1 has successfully pushed at least once to Integrator.
Login Oscar site 2
Select a time-slot to make an appointment.
In "Last Name", enter "Linker", select "Search"
A list of "Linker"s will be shown, or "No results were found!" will be shown.

If a patient is instantly selected, that means you have 1 "Linker" in Oscar site 2. Enter fewer letters in the "Last Name" entry (e.g. "Li") so that you can stay in the PATIENT'S RECORD window.
Check "Incl. Integrated Results" and select "Search" again.

If the "Incl. Integrated Results" checkbox is not found, check that Integrator push is enabled for Oscar site 2.
You should now see a "Linker, Boy" with demographic ID "Integrator XXX:X" in the list. Select it.
A new demographic "Linker, Boy" has been created in Oscar Site 2. You can cancel the appointment making if you do not intend to make one.

The new "Linker, Boy" is linked to "Linker, Boy" in Oscar site 1. All data created in one site will be shown in another.

Known Issues

Potential Incorrectly Formatted Data in Oscar's Program Table

For a newly created Oscar database, please check the "program" table:

select defaultServiceRestrictionDays from program;

If any one of the results is NULL, run the following mysql command:

update program set defaultServiceRestrictionDays=0 where defaultServiceRestrictionDays is NULL;

If this is not corrected, the integrator push will fail.

Integrator Documentation