i2b2 Release 1.7.12

Release Date: October 31, 2019

Release Summary

Release 1.7.12  contains  contains solutions for providing providing an easier install solution of i2b2, supporting various , redesigned Find Terms, totalnum counting scripts, new Authentication protocols,  integration of REDCAPAlso included are  enhancements to i2b2Weblcient, database scripts and REDCAP import. Also included are other enhancements to the i2b2 Webclient, the ACT ontology, and bug fixes

Highlight of Features

• Easier Install  with  using the  prebuilt WAR file  on a existing  widlfly instance.
• Incorport autenthication protocol support for OKTA, NTLM v2
• Provide database scripts to update Totalnum counts for Ontology Terms for POSTGESSQL, ORACLE and SQL SERVER databases.
• Enhanced Webclient Find Terms functionality-
• Improved view of Left Pane in a maximized mode
• Larger Query Results Panel view after Query run
• Integration of REDCAP data entry  into i2b2 for Ontology creation 
• Documentation updates for Apache Webserver timeout settings for previous queries run.

Installation Note

The 1.7.11 Release Notes apply to you if you are upgrading your existing i2b2 system from an earlier version of the i2b2 software.

...

Upgrading an existing i2b2 (currently installed at your site)

...

Please go to the  Upgrade Notes section for the details about upgrading your i2b2 software.

...

Upgrading your i2b2 in a SHRINE network

...

Please read the information in the  SHRINE Networks section before proceeding.

...

Installing a new instance of i2b2. (Never installed it before)

...

We recommend you refer to the i2b2 Installation Guide found on the i2b2 Community Wiki
The install guide will take you through the entire installation process.

Upgrade Notes

Information about upgrading i2b2 to version 1.7.12 can be found in this section of the release notes.

i2b2 Components

In release 1.7.12 the following i2b2 components contain changes and therefore need to be updated when upgrading your i2b2 environment.

...

Database Drivers

The JDBC drivers were updated to the following versions.

...

Upgrade Paths

The i2b2 now provides two options for upgrading your i2b2 server.

1. Continue to download the source code provided in the zip file released on www.i2b2.org/software
   
2. Install the precompiled JAR files onto your existing i2b2 server to upgrade it to 1.7.11.

...

Upgrade Software

...

Software page (i2b2 Website)

...

Software page (i2b2 Website)

...

Software page (i2b2 Website)

...

Database Changes

Release 1.7.12 involves a few changes to the i2b2 Database.  Included  totalnum counts to Ontology Terms in the demo data that is delivered with the software along with the  Stored procedures 

used for creating the counts.

Change Summary - Release 1.7.12

Did you know?

• Changes to the i2b2 server & database are listed under i2b2 Kernel (Core) Software
• Changes to the i2b2 Web Client are listed under i2b2 Web Client Software
• Additional information about the new features can be found in the Feature Details - Release 1.7.11 section located this Change Summary section.

i2b2 Kernel (Core Software)

New Features and Improvements

• [CORE-378] - Find Terms should display partial results when maximum is exceeded
• [CORE-377] - Admin interface
• [CORE-352] - Show hierarchy in Find Terms
• [CORE-348] - Improve build process, auto-build entire WAR file
• [CORE-347] - Refactor to remove XML config files
• [CORE-346] - OKTA
• [CORE-345] - Replace old Spring Libraries
• [CORE-344] - Support for NTLM2
• [CORE-345] - Replace old Spring Libraries
• [CORE-343] - Replace old Spring Libraries
• [CORE-345] - Provide totalnum counting scripts
• [CORE-341] - Add a findByName filter for results inside other results
• [CORE-338] - Add ACT ontology to i2b2 data load

Bug Fixes

...

New Feature: Role-based Ontology Protection

The top-level categories/folders in your ontology can now be optionally protected by one or more i2b2 roles (e.g. DATA_LDS, DATA_PROT, etc.) This feature allows the administrator to define one or more roles for an individual root folder in the ontology, and users without one of these roles will not be able to see the ontology item or use any of the terms in this folder.

To use this new feature and protect a root level folder, follow these steps:

1. In your TABLE_ACCESS table in your ontology database, set C_PROTECTED_ACCESS to 'Y' for the root level folder you would like to protect.
2. There is a new column in TABLE_ACCESS called C_ONTOLOGY_PROTECTION. This is where you can define one or more roles in a comma-separated list (e.g. DATA_LDS,DATA_PROT)

Example:

If you wanted to create a root level folder in your ontology called "PHI Demonstration" and only wanted users with the DATA_PROT role to be able to see it, you would make the following changes to your TABLE_ACCESS table:

...

New Feature: Workplace Folder drag and drop

Now you can drag a workplace folder to the query tool, the folder can contain sub folders.   All the concepts, previous queries, and individual patients will be displayed in the panel.

Below is the workplace with combination of available items

Image Removed                    

After the drag and drop to the query panel the list of all the items are displayed

Image Removed

New Feature: Individual Patient drag and drop from Previous Query Panel

Once a patient set is created, that patient can be dragged and dropped to the Query Tool Panel

Below is a patient set with 2 patients

Image Removed

After drag and drop of the individual patient to the query tool panel

Image Removed

New Feature: Previous Queries Upgrade in Web Client

The Previous Queries panel in the web client has been upgraded to accommodate three new options.

...

New Feature: Support for WildFly 14

The i2b2 software now officially supports WildFly 14. The primary advantages are the faster install/upgrade of i2b2 as a pre-packaged collection (WAR) and managed data source connections/pooling.

New Feature: Inter-CELL SSL Setup

Create server and client certificates (Wildfly 10 & 14)

The keytool utility stores the keys and certificates in a file termed as keystore, a repository of certificates used for identifying a client or a server. Typically, a keystore contains one client or one server's identity, which are protected by using a password.

Create a Self Signed Certificate

You can create a certificate for your server using the following command:

...

1

...

$ keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365  -dname "cn=Partners Healtbcare,o=Partners,c=US"

Now let's copy this keystore into the configuration folder of the application server:

...

1

...

$ cp server.keystore $JBOSS_HOME/standalone/configuration

Now export the server certificate in a file called server.crt:

1

...

$ keytool -exportcert -keystore server.keystore -storepass secret -keypass secret -file server.crt

Certificate stored in file <server.crt>

Now import the cert into the CA for the Java JRE:

...

1

$ keytool -import -alias i2b2server -keystore  /usr/java/latest/jre/lib/security/cacerts -file server.crt

The password might be changeit

In /opt/{wildfly} in bin run add-user.sh to create user and select (a) management user

Wildfly 10 Setup

In Wildfly 10 run jboss-cli.sh

Connect to the server

Start by creating a Security Realm which will contain the keystore and trustore references

...

1

...

/core-service=management/security-realm=SSLRealm:add

Next, for one-way SSL, set the path to the keystore, along with the keystore path and password:

...

1

...

/core-service=management/security-realm=SSLRealm/server-identity=ssl:adJavathe2d(keystore-path="server.keystore", keystore-relative-to="jboss.server.config.dir", keystore-password="secret")

Finally, set the value of Undertow's https listener to your Security Realm:

...

1

...

/subsystem=undertow/server=default-server/https-listener=default-https:write-attribute(name=security-realm,value=SSLRealm)

If the above fails edit the standalone.xml and add right after http-listener

                <https-listener name="default-https" security-realm="SSLRealm" socket-binding="https"/>

Wildfly 14 Setup

In Wildfly 14 run jboss.cli.sh

Connect to the server

...

1

...

connect

Finally, set the value of Undertow's https listener to your Security Realm:

...

1

...

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm,value=ApplicationRealm)

 Both Wildfly 10 and 14

Add the following to the axis2.xml file right after the   <transportReceiver name="http"

   <transportReceiver name="https"

                       class="org.apache.axis2.transport.http.AxisServletListener"/>

Change the crc.properties, ontology.properties and workplace.properties files to point to the https://localhost:8443

Database Changes

Change all the pm_cell_data within the PM Database to https://localhost:8443

Image Removed

After all the cells have been updated it should look like below.

Image Removed

Webclient Changes

Webclient, if using self-signed cert add the following to the index.php

        curl_setopt($proxyRequest, CURLOPT_SSL_VERIFYHOST, 0);

        curl_setopt($proxyRequest, CURLOPT_SSL_VERIFYPEER, 0);

Also into the index.php add the new url to the whitelist such as:

$WHITELIST = array(

        "http" . (($_SERVER['SERVER_PORT'] == '443') ? 's' : '' ) . "://" . $_SERVER['HTTP_HOST'],

        "http://services.i2b2.org",

        "http://127.0.0.1:9090",

        "http://127.0.0.1:8080",

        "http://127.0.0.1",

        "http://localhost:8080",

        "http://localhost:9090",

        "https://localhost:8443",

        "http://localhost"

);

Updated: i2b2 License

The i2b2 software is now made available under the terms of the Mozilla Public License (MPL) version 2.0. i2b2 is also distributed under the terms of the Healthcare Disclaimer addendum..

After reading this documentation, please go to the Quick Upgrade Guide for the details about upgrading your i2b2 software. If you are installing from scratch, refer instead to the Quick Install Guide (and optionally the full i2b2 Installation Guide).

i2b2 Release 1.7.12

Release Date: December, 2019

Highlight of Features

Backend Features

• Easier Install
  • Pre-built War file for easier distributions of the application
  • Properties files are moved from static files to a table in the database
• Authentication protocol support for OKTA and  NTLM v2.        
• Database scripts to generate Totalnum counts for Ontology Terms for POSTGRESQL, ORACLE and SQL SERVER databases
• REDCap data import into i2b2, with ontology creation from REDCap forms
• Documentation updates for Apache Webserver timeout settings for previous queries run.

Frontend Features

Redesigned Find Terms By Name

• Find terms shows the terms' contextual hierarchy, and terms that are children of other search results are not returned. Shown here: 1.7.11 (left) vs. 1.7.12 (right)
  Image Added
• Right-clicking on a term and then "Find Term in Tree" shows the entire hierarchy around the selected term.
  Image Added

New Webclient Documentation

• Included in the client and also on the Webclient Community Wiki page.

• Featuring:
  • 3-minute screencast tutorial
  • Better overviews and guideposts
  • More task-oriented teaching

Image Added

Improved view of Left Pane in maximized mode

• In maximized mode, the left pane now makes all tabs accessible.

  Image Added

Larger Query Results Panel view after Query run

When a query with breakdowns has finished, the results panel temporarily expands slightly to accommodate the breakdown graphs display.

Community-Contributed Features

Feature Configuration

Easier i2b2 Install

The i2b2 server can now be installed using a pre-built war file instead of having to build it from source, or the war file can be built from source much more easily. More information is in the updated Installation Guide. The properties files are now stored in the database.

Authentication Protocol Support for NTLM2/OKTA

•   User Set up with  OKTA Configuration:   On the Admin page, under Manage Users,

             Add a Parameter domain  and assign the values as below. Parameter value will be your institution domain name.

                                  Image Added

               Add a second parameter domain_controller as below. Parameter value will be your institution domain_controller value

                           Image Added

                Add the final parameter authentication_method as below. Parameter value will be OKTA

                            Image Added

•   User Set up with  NTLM2 Configuration:   On the Admin page, under Manage Users,

                  Add a Parameter domain  and assign the values as below. Parameter value will be your institution domain name.

                                  Image Added

                    Add a second parameter domain_controller as below. Parameter value will be your institution domain_controller value

                           Image Added

                Add the final parameter authentication_method as below. Parameter value will be NTLM2

                            Image Added

RedCap Import Setup

Anchor
redcap redcap

Currently,  the following  REDCAP Features  are supported in i2b2.

• Project level :
  •  Only one unique redcap project id  can be assigned to  each i2b2 project( system finds the first project it encounters and assigns it, so two projects cannot have same REDCAP project id:
•  Form level:
  • Renaming a Form in Redcap will create a new record in table access instead of updating the original record which means in i2b2 the original survey will still show in Ontology in addition to creating the renamed survey as a new Ontology item.
  • On adding a new Field/editing a field in the REDCAP form, the form needs to be explicitly associated with the record again to take effect in i2b2
  • Data triggers happen only on Form SAVE button.
  • Only Form  SAVE as a URL survey or Admin edit/add record Saves, triggers i2b2 Ontology creation. Other forms of Form creation in REDCAP- by Data import tool, API format, will not trigger Ontology creation in i2b2)
  • Ontology is only displayed in Tree structure format in i2b2. Pop up display (sometimes called query-by-value) is not supported. (example as below)   

                                         Image Added

• • There is no mapping of records submitted in REDCAP to existing patient_ids in i2b2. The scope of this release is limited to adding new record rows in Observation_fact table and Updating the fields of records added.
• Field level:
  • The following project fields from REDCAP  are supported in i2b2.
    • TEXT BOX
    • CHECKBOX
    • RADIO BUTTON
    • DROPDOWN
    • YES-NO
    • TRUE-FALSE
    • SLIDER / VISUAL ANALOG SCALE
    • DESCRIPTIVE TEXT
    • NOTES BOX
    • SIGNATURE
    • DYNAMIC QUERY(SQL)
  • Text box (Short text)Number and Date/Time ) with Validation capability in REDCAP - validation  will work only as a simple text String search in i2b2
  • Check box, Multiple Choice , Yes-No, True-False Form fields will appear as a Tree format in i2b2 ( Popup display is not supported)

   REDCAP SETUP CONFIGURATION

1) Set Project Params (PM_PROJECT_PARAM)

Name	Value	Description
REDCAP_TOKEN_PID_{pid}	(7B42348B7C51123432048B51EAA)	Required:    Get the pid value from the Redcap project url. Set the pid parameter name to this value Image Added Get the API Key from Redcap.  Logon to Redcap, and on the right side under applications click API.   Then, select Generate token, and use this token for the value for the parameter.         Image Added
REDCAP_SURVEY_PROJECT	(pid)	Required: Set the Value parameter to the pid value from the Redcap project url.  Image Added
REDCAP_ONTOLOGY_REFRESH	Y	Optional, Defaults to Y Y - Every time a form is submitted the i2b2 metadata ontology gets regenerated N - Do Not regenerate the metadata ontology.    NOTE:  When first setting up i2b2/redcap this needs to be set to Y at least once or the ontology will not be created.
REDCAP_ROOT_ONTOLOGY	\REDCAP\	Optional, Defaults to \REDCAP\ This is the key for the root of the REDCap ontology.
REDCAP_ONTOLOGY_FORMAT	tree	Optional, Defaults to tree This is how the ontology will be created tree - All enumerated values, Yes/No will be children on the ontology The only exception is items with checkbox, which will always be a popup
RECAP_PROTECTED_ROLE	DATA_PROT	Optional, Defaults to DATA_PROT If this redcap form has the identified value set to true, then this ontology will be protected and only users with the following i2b2 access role will be able to access it.

2) On the redcap side, set the Data Entry Trigger, it is under Project Setup → in Enable optional modules and customizations, select Additional customizations → Data Entry Trigger, and enter:

http://{i2b2 url}/i2b2/services/QueryToolService/redcapPush

Image Added

Click Test to verify connection

3) Give Editor role to the project for AGG_SERVICE_ACCOUNT( optional DATA_PROT, DEID, LDS)

Image Added

4) Submit a form and check to see if the ontology was created.

Totalnum Scripts Setup

Anchor
totalnum totalnum

1. In the Release_1-7/NewInstall/Metadata/ run the ant script to create the stored procedures.
   1. POSTGRESQL : ant -f data_build.xml db_metadata_run_total_count_postgresql
   2. ORACLE : ant -f data_build.xml db_metadata_run_total_count_oracle
   3. SQL SERVER : ant -f data_build.xml db_metadata_run_total_count_sqlserver        
2. Execute the RunTotalNum stored procedure on your database. This can take several hours. 

                 Example Usage:    

                                          Oracle:            
                                          begin
                                          RUNTOTALNUM('observation_fact','i2b2demodata');
                                          end;   

                                          Note: If you get the error as: ERROR at line 1: ORA-01031: insufficient privilege, then run the command:
                                          grant create table to (DB USER)  

                                          SQL server:              
                                          exec RUNTOTALNUM    

                                          PostgreSQL:              
                                          select RUNTOTALNUM('observation_fact','public')
                                      -- (replace 'public' by the schema name for the fact table)
                                      -- If using a schema other than public for metadata, you might need to run "set search_path to 'i2b2metadata','public' " first as well

             3.  When finished, verify it is complete by checking that c_totalnum columns in your ontology tables contain numbers (not nulls).

                These total counts will be visible in the ontology browser in the web client.

ACT Ontology Setup

Anchor
act-ontolog act-ontolog

This will allow you to install the ACT ontology as a separate project in i2b2. Note that this will create a project with ONLY the ontology - no data. At this time, using the demodata with the ACT ontology is not supported. You will need to load your own data to run queries using the ontology.

• In the Release_1-7/NewInstall/Metadata/db.properties file change the db.project from demo to act   

                          Image Added

•  Create new Project ACT  in the Admin tool
• Add  AGG SERVICE Account to the Project
• Add new dblookup-row  with parameters  under CRC, Ontology and workplace to set up the project path( example as in below)   

                               Image Added

•   Run the ant script against create_metadata_tables_release_1-7 and db_metadata_load_data. 

                     This will create  the new  ACT Ontology structure under project ACT.

                      Image Added

Using Extended Query-By-Value Flags

Anchor
flags flags

An expanded set of lab flag values can be easily modified by users to support their needs or expanded to the full set of HL7/LOINC flag values. The expanded list is toggleable via an added config setting in the i2b2_ui_config.js. (Note: Only numeric lab results have the flag functionality included.)

With the expanded set of lab values, the base 'A','L','H' are omitted to prevent collisions with things like "CH" (Critical High) or "CL" (Critical Low) due to the indexOf function call to determine if a flag is in the list.

To use the expanded lab flag set, make ETL changes to accommodate the expanded list of values you would like to use and modify i2b2_ui_config.js to match.

Configuring the Expanded Webclient Left Pane

Anchor
left-pane left-pane

Image Added

To set the webclient to start with the left pane in the new expanded mode, make sure this new parameter is added to i2b2_config.js. 

startZoomed: true

The .zip file for this release defaults to this mode.

Changelog

Database Drivers

The JDBC drivers were updated to the following versions.

i2b2 Database Changes

• Small changes to the i2b2 Database. 
  • Property files were moved into the database in the new Hive table HIVE_CELL_PARAMS.
  • Query type classname property moved from the properties file to the CRC table QT_QUERY_RESULT_TYPE in a new CLASSNAME field
• Totalnum counts to Ontology Terms in the demo data that is delivered with the software along with the  Stored procedures used for creating the counts.
• ACT Ontology

i2b2 Server and Client Changes

New Features and Improvements

• [CORE-378] - Find Terms should display partial results when maximum is exceeded
• [CORE-377] - Admin interface
• [CORE-352] - Show hierarchy in Find Terms
• [CORE-348] - Improve build process, auto-build entire WAR file
• [CORE-347] - Refactor to remove XML config files
• [CORE-346] - OKTA
• [CORE-345] - Replace old Spring Libraries
• [CORE-344] - Support for NTLM2
• [CORE-345] - Replace old Spring Libraries
• [CORE-343] - Replace old Spring Libraries
• [CORE-345] - Provide totalnum counting scripts
• [CORE-341] - Add a findByName filter for results inside other results
• [WEBCLIENT-310] - Mauro Bucalo contribution: totalnum in find, improved date filters
• [WEBCLIENT-309] - Find Terms should display partial results when maximum is exceeded
• [WEBCLIENT-308] - UNC Contribution: Configurable extended lab result flags
• [WEBCLIENT-306] - Beth Israel contribution: commas in counts, query option infrastructure
• [WEBCLIENT-299] - Fully spell out words in tabs
• [WEBCLIENT-298] - open web issue management for i2b2
• [WEBCLIENT-287] - Improved term info panel
• [WEBCLIENT-285] - New webclient documentation
• [WEBCLIENT-282] - Improve find terms view
• [WEBCLIENT-281] - Left side panels tabbed instead of stacked
• [WEBCLIENT-279] - Query status window resize to show graphs
• [WEBCLIENT-174] - Previous query run as a query-in-query containing unsupported concepts does not draw the timeline
• [WEBCLIENT-104] - Add Print functionality to i2b2 web client help files

Bug Fixes

• [CORE-367] - When a SHRINE query is rerun in i2b2 the date parameter seems to be lost.
• [CORE-366] - Error on API request on endpoint /i2b2/services/QueryToolService/publishDataRequest
• [CORE-308] - Full Request XML message is stored in the QT_PDO_QUERY_MASTER table
• [CORE-362] - db_metadata_load_identified_data does not exist
• [CORE-358] - Issues with 1.7.10 VM image
• [CORE-353] - DBLookup pages - not all fields appear
• [CORE-333] - Query run with Text search with words that contain a space and a dash is erroring out
• [CORE-332] - OracleLarge db give db error for Ontology terms 'Encounters', 'Enrollment, 'VitalSigns'
• [CORE-231] - CRC: PDO query does not escape characters
• [CORE-224] - SQL Server: Database error when no start_date on a temporal query
• [CORE-222] - Visit_Dimension event set in PDO not returning
• [WEBCLIENT-312] - Find Term tab- context menu shows Find Term in Tree" item without any item selection
• [WEBCLIENT-311] - Find Terms- Search by "Any Category" not displaying right msg if no match found
• [WEBCLIENT-303] - Find Terms - Category Diagnosis ICD10 showing as Diagnosis
• [WEBCLIENT-302] - Find Terms- Search by term matching more than 2000 count -resulting in application
• [WEBCLIENT-294] - Webclient Reports "QUERY CANCELLED" While Query Is Still Running
• [WEBCLIENT-293] - A large number of results when searching by name hangs the webclient
• [WEBCLIENT-288] - Right Click on Find Terms Persists
• [WEBCLIENT-273] - Query report displays individual pt as "undefined" on loading the previous query after run
• [WEBCLIENT-272] - temporal query with workplace contents in constraint population panel not running
• [WEBCLIENT-254] - 2b2 Admin page not displaying all the rows from dblookup table for the projects
• [WEBCLIENT-231] - Able to set Date constraint on previous queries/ptset as concept
• [WEBCLIENT-223] - Admin uses last URL from PM_CELL_DATA in getAllDbLookups call
• [WEBCLIENT-159] - Run/Rerun a temporal query without events is not displaying msg that minimum 2 events are required