Migration 12_1 to OSCAR 15

Preface

This migration instructions allows people on OSCAR 12_1 migrate to OSCAR 15.

Document Version History

• v1.0 – initial OSCAR 15 version published to oscarmanual.org – May 10, 2016
• v1.1 – added instructions to increase tread stack if gets indexing error – July 6, 2016
• v1.2 – corrected path for new document directory – Oct 24, 2016

Migrating from older OSCAR installations 

Note that BC region upgrades have not been tested.

OSCAR 15 is not an incremental upgrade to OSCAR 12.  Most systems and many conventions have been changed, and an in place upgrade is neither recommended nor supported.  These instructions start with a new server and leaves the old server intact as business continuity security.  There is nothing like production data to humble programmers.  Test your conversion on a backup first prior to committing to convert live data over.

PREREQUISITES

1. Update OSCAR 12_1 to latest DEB and run it at least once to ensure its in the latest form and ready to convert.
2. Create a backup of your oscar_12_1 database.
3. Install OSCAR 15 with demo data on a fresh VM or machine with standard property files that is separate from your existing OSCAR instance.

1. Create Blank Database

After having tested the new OSCAR 15 installation to confirm that it works, take the opportunity to retrieve the Rourke 2014 eform code with the following (supply your MySQL password for the ******)

mysqldump --no-create-info -uroot -p******* oscar_15 eform > RourkeEform.sql

Now you can now safely drop the schema.

mysql -uroot -p****** -e "drop database oscar_15;"

Now create a blank oscar_15 schema that defaults to new best practices database engines and encoding.

mysql -uroot -p****** -e "CREATE DATABASE IF NOT EXISTS oscar_15 DEFAULT CHARACTER SET utf8  DEFAULT COLLATE utf8_general_ci;"

2. Clean The Backup

The standard backup historically has been using latin1 encoding on MyISAM database engine.  For best results for using Integrator, support for foreign characters, and keeping up to date this needs to be changed to InnoDB and UTF8.  Its much safer and quicker to convert the data when it is in the form of a backup than in the server, so we will do it now.

Change to your home directory on your new server.

cd ~

De-encrypt your existing oscar_12_1 schema backup in preparation of loading it to the new server.   The standard backup specifies the engine and encoding but it is usually to large to edit using GUI editors.

Instead you can change all the encoding and engines with the following sed command.  These changes will also prevent your backup from deleting the legacy table structures you just added.

sed 's/DEFAULT CHARSET=latin1/DEFAULT CHARSET=UTF8/g; s/ENGINE=MyISAM/ENGINE=InnoDB/g; s/DROP TABLE IF EXISTS `formRourke2009`;//; s/CREATE TABLE `formRourke2009`/CREATE TABLE IF NOT EXISTS`formRourke2009`/;s/DROP TABLE IF EXISTS `formONAREnhanced`;//; s/CREATE TABLE `formONAREnhanced`/CREATE TABLE IF NOT EXISTS`formONAREnhanced`/; ' <OscarBackup.sql > CleanBackup.sql

3. Load Legacy Structures

Now populate the blank database with the structures of two legacy MyISAM tables (`formRourke2009` and `formONAREnhanced` cannot be converted and will be retained in their current state for backwards compatibility). 

mysql -uroot -p****** oscar_15 < /usr/share/oscar-emr/legacyMyISAM.sql

4. Restore the Backup

Then load the cleaned backup into the empty oscar_15 schema.  A 10GB (1.8GB gziped) backup may easily take a half hour so... get a coffee!

mysql -uroot -p****** oscar_15 < CleanBackup.sql

5. Update the Schema to oscar_15

Run the migration script that brings the OSCAR schema from version 12.1.1 to 15.   

mysql -uroot -p****** oscar_15 < /usr/share/oscar-emr/oscar_12_1_1_to_oscar_15.sql

On any error the conversion will stop at that point and the system will be broken.  You will need to fix the error(s) in your data at that line number and re run the scripts from a blank oscar_15 database from step 1, skipping step 2.
NOTE:  If the script fails with something like

"ERROR 1062 (23000) at line 1443: Duplicate entry '1838-rxInteractionWarningLevel' for key 'uk_demo_ext'"

it is likely that you need to edit  /etc/mysql/my.cnf to set the tread_stack=256K or greater

6. Patch the Schema

Last minute tweaks that came out after the conversion script was made are in a special patch file 

mysql -uroot -p****** oscar_15 < /usr/share/oscar-emr/patch.sql

7. Copy over OscarDocuments

You will also want to copy over the OscarDocuments from your backup.  You can copy them using rsynch over the network from your previous server with something like the following:.

rsync -avz --progress --chown=tomcat7:tomcat7 --rsh='ssh -p22' {USER}@{OSCAR 12 SERVE IP}:/var/lib/tomcat6/webapps/OscarDocument/oscar_mcmaster/ /usr/share/oscar-emr/OscarDocument/oscar/

8. Migrate ONAREnhanced (optional)

Navigate to Admin> Updates and Migrations > Migrate ONAREnhanced and run the report/utility

9. Install Non-Free components (optional)

In the province of Ontario, regulatory requirement mandates OSCAR to use a commercial drug interaction database.  To configure this Lexicomp/Medi‐span database, add the following line into /usr/share/tomcat7/drugref2.properties replacing ????? with the licence key. Please contact your OSP for instructions to purchase a licence key. If you do not have an OSP, contact OSCAR EMR directly for the license key. 

licence_key=??????????

For oscar.properties add the following to the properties file

RX_INTERACTION_LOCAL_DRUGREF_REGIONAL_IDENTIFIER=yes

OSCAR-EMR has obtained a license for Canadian OSCAR users for the 2014 Rourke.  This is at no cost to the eligible end user and is installed automatically by the DEB.  For OSCAR 15 upgrades the main eform code you retrieved in part 1 of this Appendix while the other files will be already loaded.  Edit the sql by hand (the fid of your desired eforms need to be adjusted for your system prior to running the insert) and then run it.

mysql -uroot -p****** oscar_15 < RourkeEform.sql

10. Activate K2A (its easy and free!)

You will want to activate Know2Act as it is a repository of pre made eforms, report templates, drug information, clinical tools and other contributions by your peers in the OSCAR community.  Go to https://www.know2act.org and register.  Then go to Administration > Integration > Know2Act Configuration.  Insert your clinic name into the text box and click Initialize Know2Act.

A K2A tab will appear on your schedule screen.  Click on it and enter your registration credentials and that's it!.

Note that this describes a quick way to get up and running.  You will still want to hand adjust the property files to meet your needs.