Plugins

One of the exciting features of the latest i2b2 upgrade in ACT is the addition of two plugins to assist in the local identification of patients. Both plugins are run in your site's local i2b2 web client.

SHRINE-to-i2b2 Connector plugin enables a local site admin (i.e. a user with MANAGER role in the local i2b2 project that SHRINE uses) to easily view all SHRINE queries that come into your site's SHRINE node. The plugin allows the local site admin to filter all incoming queries by flag status and search by query name.
Image Added
Patient Data Exporter allows the local data concierge to download a list of i2b2 patient numbers for a specified patient set of interest. These i2b2 patient numbers can then be referenced back to patient MRNs (using your site's own process) for study recruitment purposes.
Image Added

These plugins were distributed in a pre-packaged i2b2 1.7.12A web client as part of the upgrade process. You can check if your version of your i2b2 web client contains these plugins by confirming if the existence of the folder /webclient/js-i2b2/cells/plugins/ACT/. If you do not see the 'ACT' folder, you can download the pre-packaged web client below which will contain these plugins already enabled for use.

Download

Description	i2b2 Released Version	Download Link	Requirements
i2b2 1.7.12A web client with pre-packaged two ACT plugins	1.7.12A	i2b2-act-webclient-1712a.zip	You are running at least i2b2 1.7.12A in the ACT production network.

Anchor

	i2b2-upgrade-v1710-stepByStep-WildFly
	i2b2-upgrade-v1710-stepByStep-WildFly

Step-by-Step Instructions for installing and configuring ACT plugins

Install the new webclient on your web server

UI Steps

size	small

UI Step

Unzip act-webclient-1712a.zip to your web server directory. This is usually where your local i2b2 web client is running (not your SHRINE web client). Example on Linux running Apache, below:

Code Block

language	bash
title	Linux Example

$ unzip i2b2-act-webclient-1712a.zip -d /var/www/html/

This will extract the folder 'i2b2-act-webclient' in your web directory (e.g. /var/www/html/i2b2-act-webclient/)

UI Step

Configure the /i2b2-act-webclient/i2b2_config_data.js file. If you have an existing i2b2_config_data.js that is setup for your local ACT i2b2, you can copy and replace this file.

This is a standard i2b2 web client configuration as outlined in section 1.4.2 Domain Configuration of the i2b2 installation guide.

UI Step

Configure the /i2b2-act-webclient/ACT_configuration.php file. This configuration file contains the URL to your SHRINE node's 'admin' API. You should modify the $shrine_admin_url variable depending on your version of SHRINE.

For SHRINE 3.0+ versions: $shrine_admin_url = 'http://your-shrine-server:port/shrine-api/aim3/xml';
For SHRINE 2.x versions: $shrine_admin_url = 'http://your-shrine-server:port/shrine/rest/i2b2/admin/request';

This configuration is required for the SHRINE-to-i2b2 Connector plugin to operate.

UI Step

You can skip this step if you are using the pre-packaged act-webclient-1712a.zip file above. Your plugins are already configured in i2b2_loader.js.

Configure the /i2b2-act-webclient/js-i2b2/i2b2_loader.js file. This configuration file controls which i2b2 web client plugins are enabled in your web client.

Upgrade i2b2 Databases to 1.7.12A

Run the following upgrade scripts on your i2b2 database instance, where {db} can be Oracle, sqlserver or postgresql. Note: The example scripts below are examples ONLY. The actual .sql scripts are provided in the zip file download above.

Open the file: /i2b2/data/Crcdata/scripts/crc_create_query_{db}.sql and run the last three relevant sections (upgrading from 1.7.09c all the way to 1.7.12):

For example, for SQL server:

--==============================================================
-- Database Script to upgrade CRC from 1.7.09c to 1.7.10
--==============================================================
-- New column added to support new SQL breakdowns - roles based access
alter table QT_QUERY_RESULT_TYPE add USER_ROLE_CD VARCHAR(255);
--==============================================================
-- Database Script to upgrade CRC from 1.7.10 to 1.7.11
--==============================================================
insert into QT_PRIVILEGE(PROTECTION_LABEL_CD, DATAPROT_CD, HIVEMGMT_CD) values ('SETFINDER_QRY_PROTECTED','DATA_PROT','USER')
--==============================================================
-- Database Script to upgrade CRC from 1.7.11 to 1.7.12
--==============================================================
alter table QT_QUERY_RESULT_TYPE add CLASSNAME VARCHAR(200)
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientSetGenerator' where NAME='PATIENTSET'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultEncounterSetGenerator' where NAME='PATIENT_ENCOUNTER_SET'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientCountGenerator' where NAME='PATIENT_COUNT_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultGenerator' where NAME='PATIENT_GENDER_COUNT_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultGenerator' where NAME='PATIENT_VITALSTATUS_COUNT_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultGenerator' where NAME='PATIENT_RACE_COUNT_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultGenerator' where NAME='PATIENT_AGE_COUNT_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientSQLCountGenerator' where NAME='PATIENT_LOS_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientSQLCountGenerator' where NAME='PATIENT_TOP20MEDS_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientSQLCountGenerator' where NAME='PATIENT_TOP20DIAG_XML'
;
update QT_QUERY_RESULT_TYPE set CLASSNAME='edu.harvard.i2b2.crc.dao.setfinder.QueryResultPatientSQLCountGenerator' where NAME='PATIENT_INOUT_XML'
;

Open the file: /i2b2/data/Hivedata/scripts/upgrade_{db}_i2b2hive_tables.sql and run the last required section:

For example, for SQL server:

CREATE TABLE HIVE_CELL_PARAMS (
ID INT NOT NULL,
DATATYPE_CD VARCHAR(50) NULL,
CELL_ID VARCHAR(50) NOT NULL,
PARAM_NAME_CD VARCHAR(200) NOT NULL,
VALUE VARCHAR(MAX) NULL,
CHANGE_DATE DATETIME NULL,
ENTRY_DATE DATETIME NULL,
CHANGEBY_CHAR VARCHAR(50) NULL,
STATUS_CD VARCHAR(50) NULL,
CONSTRAINT HIVE_CE__PK PRIMARY KEY(ID)
);
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(33, 'T', 'CRC', 'queryprocessor.jndi.queryinfolocal', 'ejb.querytool.QueryInfoLocal', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(31, 'T', 'CRC', 'queryprocessor.jndi.querymanagerlocal', 'ejb.querytool.QueryManagerLocal', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(37, 'T', 'CRC', 'queryprocessor.jndi.querymanagerremote', 'ejb.querytool.QueryManager', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(61, 'T', 'ONT', 'applicationName', 'Ontology Cell', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(63, 'T', 'CRC', 'applicationName', 'CRC Cell', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(62, 'T', 'ONT', 'applicationVersion', '1.7', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(64, 'T', 'CRC', 'applicationVersion', '1.7', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(16, 'T', 'CRC', 'edu.harvard.i2b2.crc.analysis.queue.large.jobcheck.timemills', '60000', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(14, 'T', 'CRC', 'edu.harvard.i2b2.crc.analysis.queue.large.maxjobcount', '1', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(13, 'T', 'CRC', 'edu.harvard.i2b2.crc.analysis.queue.large.timeoutmills', '43200000', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(15, 'T', 'CRC', 'edu.harvard.i2b2.crc.analysis.queue.medium.jobcheck.timemills', '60000', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
VALUES(12, 'T', 'CRC', 'edu.harvard.i2b2.crc.analysis.queue.medium.maxjobcount', '4', NULL, NULL, NULL, 'A');
INSERT INTO HIVE_CELL_PARAMS(ID, DATATYPE_CD, CELL_ID, PARAM_NAME_CD, VALUE, CHANGE_DATE, ENTRY_DATE, CHANGEBY_CHAR, STATUS_CD)
... (shortened)

Update the datasource (*-ds.xml) files in your deployment directory

Copy *-ds.xml files from the backup folder to wildfly-1#.0.1.Final/standalone/deployments

Edit the following files crc-ds.xml, ont-ds.xml, pm-ds.xml, work-ds.xml
and replace ALL the <driver>{something}.jar</driver> with

Migrate cell properties: In 1.7.12, cell properties have been moved to the database, in a new table called HIVE_CELL_PARAMS. If any cell properties were previously changed, they will need to be manually updated in the database. After this, the properties files can be deleted to prevent confusion.

More documentation on setting cell properties is available at this page. Most commonly, the AGG_SERVICE_ACCOUNT password will need to be updated. Generally, the cell URLs do not need to be configured anymore, as the hostname and port is now auto-detected.

UI Step

In /i2b2/data/ folder

CRC

Hive

Ontology

Open the file: /i2b2/data/Metadata/scripts/ont_{db}.sql and run the script:

For example, for SQL server:

alter table TABLE_ACCESS add C_ONTOLOGY_PROTECTION VARCHAR(MAX);

Note: For ACT, you'll want to apply this statement to both your local i2b2 ACT ontology, and your SHRINE ACT ontology (if you use two separate i2b2 projects).

PM

Open the file: /i2b2/data/Pmdata/scripts/upgrade_{db}_i2b2pm_tables.sql and run the last relevant section (upgrading from 1.7.09c):

For example, for SQL server:

ALTER TABLE PM_USER_LOGIN
DROP PRIMARY KEY;

CREATE INDEX PM_USER_LOGIN_IDX ON PM_USER_LOGIN(USER_ID, ENTRY_DATE);

UI Step

Oracle

SQL Server

PostgreSQL

<driver>ojdbc8.jar</driver>

<driver>mssql-jdbc-7.4.1.jre8.jar</driver>

<driver>postgresql42.2.8.jar</driver>

UI Step

Example

Properties files are stored at /opt/wildfly-{version}.Final/standalone/configuration/ on Linux and c:\opt\wildfly-{version}.Final\standalone\configuration\ on Windows. The table can be edited with a SQL editor in hive_cell_params.

Add the MANAGER role to your local i2b2 account(s) for your ACT i2b2 project.

If you are unsure about what your local i2b2 project is called, the information can be found in your shrine configuration file (/opt/shrine/tomcat/lib/shrine.conf) under shrine.hiveCredentials.crcProjectId:

shrine {
	...
	hiveCredentials {
		...
		crcProjectId = 'demo'
	}
	...
}

Once you have confirmed your local i2b2 project ID that SHRINE uses, you should add the following i2b2 role for your i2b2 account in your PM_PROJECT_USER_ROLES table

PROJECT_ID	USER_ID	USER_ROLE_CD	CHANGE_DATE	ENTRY_DATE	CHANGEBY_CHAR	STATUS_CD
demo	user_id	MANAGER	date	date	NULL	A

If the account you login with does not have the MANAGER role, you will not see the SHRINE-to-i2b2 Connector or Patient Data Exporter plugins in the list of available plugins.

Note: any changes made in your HIVE_CELL_PARAMS table will require you to restart Wildfly/i2b2 for the changes to take affect.

Backup your existing i2b2_config_data.js from your web server

On your webclient backup your existing i2b2_config_data.js to a folder outside of your web server.

UI Step

Verify your installation

UI Expand

expanded	true
title	Test web client

UI Step

UI Expand

title	Linux Example

On Linux, move the folder /var/www/html/webclient/ and save it to a different location outside of /var/wwww/html/webclient

UI Expand

title	Windows

On Windows, move the folder c:\inetpub\webclient and save it to a different location outside of c:\inetpub\webclient

UI Step

UI Expand

title	Linux

On Linux, extract the i2b2webclient-1712.zip to the folder /var/www/html/webclient/ and copy the backup i2b2_config_data.js to /var/wwww/html/webclient

UI Expand

title	Windows

On Windows, extract the i2b2webclient-1712.zip c:\inetpub\webclient and copy the backup i2b2_config_data.js to c:\inetpub\webclient

UI Step

Start WildFly

Code Block

language	powershell
title	Linux Example
collapse	true

$ /opt/wildfly-{version}.Final/bin/standalone.sh -b 0.0.0.0 &

UI Step

Verify your upgrade

UI Expand

title	Test Web Client

Navigate to your local i2b2 Web Client in your preferred browser and verify you are able to log on and perform standard i2b2 functions. (e.g. Run queries, retrieve previous queries, view breakdowns, etc.). Click on the Analysis Tools at the top-right, you should see the SHRINE-to-i2b2 Connector and Patient Data Exporter plugins.

Image Added

Need help? If you run into any issues, please check out the Troubleshooting Tips for i2b2 & SHRINE page, and/or post your issues to the ACTtecdh mailing list

Anchor

	i2b2-upgrade-zip-contents
	i2b2-upgrade-zip-contents

Versions Compared

Old Version 4

New Version Current

Key

Plugins

Step-by-Step Instructions for installing and configuring ACT plugins

Pages

Recently updated

Page History

Versions Compared

Old Version 4

New Version Current

Key

Plugins

Step-by-Step Instructions for installing and configuring ACT plugins

Pages

Recently updated