= i2b2 HowTo Upgrade to Version 1.6

Tags: [[i2b2]] [[HowTo]] [[Upgrade]]

To upgrade an instance of i2b2 from version 1.5 to version 1.6 first you need to download the upgrade package from here ('''''when I've put it there''''') and unzip it into a location on the appropriate server.  The process is then as follows:

1. Back up existing system.
1. Change config values.
1. Run scripts and do manual processes.
1. Test upgrade.

These steps are laid out in more detail below.

== 1. Back up existing system

The following resources need packing up:

1. Databases:
 1. Common databases: hive and PM
 2. Project specific databases: data, work and meta
1. JBoss directory
1. Web client directory

== 2. Change config values

Config values have to be changed in 2 files in the i2b2-upgrade-1.6/procedures/config directory:
1. config.properties
1. defaults.sh

=== config.properties
These values are used to update the i2b2 config settings.  Add the connection details for common databases and also the project specific databases.

=== defaults.sh
These values are used by the upgrade scripts.  In order for the scripts to upgrade all the projects and their ontologies these should be provided as arrays in the form of space separated strings.  For each project in the projects array create a dictionary item in the onotology dictionary containing a list of that project's ontologies (space separated).

== 3. Run scripts and do manual processes

In order to run the script you will need to become a super user:

{{{
#!sh
sudo su
}}}

then {{{cd}}} into the base directory of the upgrade procedures {{{i2b2-upgrade-1.6/procedures}}} and run the following command:

{{{
#!sh
export I2B2_INSTALL_HOME=$PWD
}}}

then cd into the script directory {{{i2b2-upgrade-1.6/procedures/bin/installs}}} and do the following procedure:

NB {{{[run identifier]}}} is used to create a working directory for the current run.  It can be any valid directory name and must be the same for every script.  E.g., 'Upgrade1'

1. Run the script {{{./1-acquisitions.sh [run identifier]}}} - this downloads the i2b2 packages.
2. Run the script {{{./2-tailor-jboss.sh [run identifier]}}} - it doesn't do anything, but on the up side it's unlikely that it will go wrong ;)
3. Run the script {{{./3-data-install.sh [run identifier]}}} - this could go wrong so hold your hats.  It runs SQL scripts to upgrade the databases.
4. Run the script {{{./4-pm-install.sh [run identifier]}}} - this updates the PM cell.  At the end of the script it displays an update statement that you need to run in the PM database.
5. Run the script {{{./5-ont-install.sh [run identifier]}}} - this updates the ONT Cell.
6. Logon to the site admin site http://[server]/admin/ and create the user AGG_SERVICE_ACCOUNT with the password set with the usual password.
7. For each project add the user AGG_SERVICE_ACCOUNT and give it user and aggregated data roles.
8. For each project add four records to the table QT_BREAKDOWN_PATH in the data database with the following names:
 * PATIENT_GENDER_COUNT_XML
 * PATIENT_RACE_COUNT_XML
 * PATIENT_VITAL_STATUS_XML
 * PATIENT_AGE_COUNT_XML

The Value for each record should be the path to the relevant group item in the ontology, using the following format '!\\[Ontology table name]\[Value of the C_FULLNAME column from the ontology table]'

9. Run the script {{{./6-crc-install.sh [run identifier]}}}
10. Run the script {{{./7-work-install.sh [run identifier]}}}
11. Run the script {{{./8-fr-install.sh [run identifier]}}}
12. Download the Web Client Zip file from i2b2 website and {{{scp}}} it to the relevant machine.  Unzip the file.
13. Move the current web client folder {{{/var/www/main}}} to a back up location and move the unzipped web client folder to be the web folder {{{/var/www/main}}}.
14. Copy the file {{{i2b2_config_data.js}}} from the backed up web client folder to the new web client folder.
15. Copy plugins from the backed up web client folder to the new web client folder.
16. Because modifiers are now being used, the Instance_Num column of the Observation_Fact table becomes very important.  Therefore we need to create instance numbers for observation facts that didn't have them before using this script:

{{{#!sql
BEGIN TRANSACTION

UPDATE o
SET INSTANCE_NUM = a.rnum
FROM Observation_Fact o
JOIN (
	SELECT  row_number() OVER(PARTITION BY encounter_num, patient_num, concept_cd, provider_id, start_date, modifier_cd ORDER BY encounter_num, patient_num, concept_cd, provider_id, start_date, modifier_cd ) as rnum,
			obf.*
	FROM	Observation_Fact obf
	) a ON	a.Encounter_Num = o.Encounter_Num
		AND a.Patient_Num = o.Patient_Num
		AND a.Concept_Cd = o.Concept_Cd
		AND a.Provider_Id = o.Provider_Id
		AND a.Start_Date = o.Start_Date
		AND	a.Modifier_Cd = o.Modifier_Cd

-- COMMIT
}}}

[[BackLinks]]