i2b2 Release 1.7.08 Release Notes 

Release Date: October 7, 2016

1.7.08 Release Summary

Release 1.7.08 contains a number of new features as well as bug fixes. Below are a few highlights of the changes included in this release.

Information about the other changes can be found in the sections that follow this one.

JBoss Updated to WildFly

In order to address some of the security vulnerabilities that exist in some JBoss installations, the i2b2 Server has been upgraded to use WildFly. In 2014 Red Hat renamed their JBoss Application Server to WildFly and their latest version (WildFly 10) addresses the known security vulnerabilities.

Note The Third Party Software Changes section contains additional information on upgrading WildFly as well as other 3rd party software. Although we recommend upgrading to WildFly, we do recognize that some sites may not be in a position to upgrade their existing JBoss 7. In the section labeled i2b2 Property Settings for WildFly 10 and JBoss 7 we have documented all the places you will need to modify the paths in order to use 1.7.08 with your existing JBoss 7. We have also included some additional information that you will need to be aware of before using 1.7.08 with your existing JBoss,

SQL Server: Option to Improve Query Performance

New parameter to use temp table constraint instead of 'WITH' clause.

Large data warehouses that contain broad and deep ontologies run the risk of CRC queries having a slow response time. In this release (1.7.08) a new parameter has been added to the crc.properties file. This new parameter allows a site to use a temp table instead of a 'WITH' clause when running a CRC query.

Additional information about this new feature can be found in the Improvement / New Feature Details section under the SQL Server:

Option to Improve Query Performance heading.

Improvements to the Processing of Queueing Queries

In the Previous Query display, new statuses provide users with additional information that accurately reflects the current status and location of the query. The new statuses are:

SMALL_QUEUE

SMALL_QUEUE_RUNNING

MEDIUM_QUEUE

MEDIUM_QUEUE_RUNNING

LARGE_QUEUE

LARGE_QUEUE_RUNNING

In addition to updating the status of queries, an additional feature was added to the Web Client that makes these statuses visible to users.

The query status can be seen in Previous Queries as well as in Show Query Status.

A complete list of all the statuses as well as additional information about this new feature can be found in the Improvement / New Feature Details section under the Improvements to the Processing of Queueing Queries heading.

SHRINE Approval

SHRINE Release 1.21.2 has been tested with i2b2 1.7.08 Release and has been approved by the SHRINE Team

Installation Notes

This release note applies to you if you are upgrading to 1.7.08 from an earlier version of i2b2.

If you are installing 1.7.08 from a computer running the i2b2 Workbench, ensure that the workbench and all eclipse applications are closed prior to installing this release.

If you are installing a new instance of i2b2 we recommend you refer to the installation documentation found on the i2b2 community wiki. This documentation will guide you through the entire installation process.

Upgrade Notes

i2b2 Release 1.7.08 contains changes to the following software components:

Database Scripts i2b2 Server i2b2 Web Client

Third Party Software Changes

In release 1.7.08 the i2b2 Server has been updated to use the following versions of third party software. These updates were done to address some security concerns with the third party software used by the i2b2

1. Apache Ant has been upgraded to 1.9
2. Apache Axis2 has been upgraded to 1.7.1
3. Java JDK has been upgraded to 8.0
4. JBoss has been upgraded to WildFly 10

3rd Party Software Versions and Links

The following table contains all the information needed to update your 3rd party software. In addition to the version information, the table contains links both to the Vendor's documentation as well as the appropriate chapter in the i2b2 Installation Guide located on the i2b2 Community Wiki.

3rd Party Software	Version	Download Link	Vendor Documentation	i2b2 Installation Guide	i2b2 Notes
Apache Ant	1.9	Apache Ant 1.9 Software	Ant's manual and API documentation is included in the binary distribution.
Apache Axis2	1.7.1	Axis2 1.7.1 Software	Installation Guide	Apache Axis2	Download the WAR Distribution File
Java JDK	8.0	JDK 8 Software		Java JDK	Reminder: Update your JAVA_HOME environment variable to point to JDK 8.0
WildFly	10	WildFly 10 Software	Getting Started Guide

i2b2 Property Settings for WildFly 10 and JBoss 7

Warning As stated earlier, the i2b2 team made the decision to upgrade to WildFly 10 and JDK 8 in order to address known security vulnerabilities with JBoss. In order for the i2b2 server (1.7.08) to work correctly, we recommend you update your environment to use WildFly 10 and JDK 8. However, if you are currently using JBoss 7 and do not want to upgrade your environment to use WildFly there are a few things you need to be aware of. 1.  Release 1.7.08 was not tested with JBoss 7, therefore we cannot guarantee the stability of the release if you continue to use JBoss 7. We can however confirm the i2b2 server (1.7.08) was tested with WildFly 10 and JDK 8 and does work correctly. 2.  JDK 8 does not work with JBoss 7. If you are upgrading to JDK8 then you have to upgrade to WildFly If you are upgrading to WildFly and JDK 8 you need to do these upgrades before you upgrade your i2b2 server code.

The property settings delivered with i2b2 version 1.7.08 are pointing to WildFly. For those sites that are currently using JBoss 7 and are not ready to upgrade to WildFly 10 you will need to change the path information to point to JBoss 7. The files and properties that need to be modified are in the next section.

WildFly Property Modifications

CRC Cell Property Changes

File Name: crc_application_directory.properties

Location: edu.harvard.i2b2.crc/etc/spring/

WildFly 10 path:	edu.harvard.i2b2.crc.applicationdir=/opt/wildfly-10.0.0.Final/standalone/configuration/crcapp
JBoss 7 path:	edu.harvard.i2b2.crc.applicationdir=/opt/jboss-as-7.1.1.Final/standalone/configuration/crcapp

File Name: build.properties

Location: edu.harvard.i2b2.crc/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

File Repository Cell Property Changes

File Name: fr_application_directory.properties

Location: edu.harvard.i2b2.fr/etc/spring/

WildFly 10 path:	edu.harvard.i2b2.fr.applicationdir=/opt/wildfly-10.0.0.Final/standalone/configuration/frapp
JBoss 7 path:	edu.harvard.i2b2.fr.applicationdir=/opt/jboss-as-7.1.1.Final/standalone/configuration/frapp

File Name: build.properties

Location: edu.harvard.i2b2.fr/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

Identity Management (IM) Cell Property Changes

File Name: im_application_directory.properties

Location: edu.harvard.i2b2.im/etc/spring/

WildFly 10 path:	edu.harvard.i2b2.im.applicationdir=/opt/wildfly-10.0.0.Final/standalone/configuration/imapp
JBoss 7 path:	edu.harvard.i2b2.im.applicationdir=/opt/jboss-as-7.1.1.Final/standalone/configuration/imapp

File Name: build.properties

Location: edu.harvard.i2b2.im/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

Ontology Cell Property Changes

File Name: ontology_application_directory.properties

Location: edu.harvard.i2b2.ontology/etc/spring/

WildFly 10 path:	edu.harvard.i2b2.ontology.applicationdir=/opt/wildfly-10.0.0.Final/standalone/configuration/ontologyapp
JBoss 7 path:	edu.harvard.i2b2.ontology.applicationdir=/opt/jboss-as-7.1.1.Final/standalone/configuration/ontologyapp

File Name: build.properties

Location: edu.harvard.i2b2.ontology/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

PM Cell Property Changes

File Name: build.properties

Location: edu.harvard.i2b2.pm/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

Server-Common Changes

File Name: build.properties

Location: edu.harvard.i2b2.server-common/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

Workplace Cell Property Changes

File Name: workplace_application_directory.properties

Location: edu.harvard.i2b2.workplace/etc/spring/

WildFly 10 path:	edu.harvard.i2b2.workplace.applicationdir=/opt/wildfly-10.0.0.Final/standalone/configuration/workplaceapp
JBoss 7 path:	edu.harvard.i2b2.workplace.applicationdir=/opt/jboss-as-7.1.1.Final/standalone/configuration/workplaceapp

File Name: build.properties

Location: edu.harvard.i2b2.workplace/

WildFly 10 path:	jboss.home=/opt/wildfly-10.0.0.Final
JBoss 7 path:	jboss.home=/opt/jboss-as-7.1.1.Final

Change Summary - i2b2 Core Software - Release 1.7.08

Improvements

[CORE-214] - Upgrade JBoss to WildFly

[CORE-216] - Change GetTermInfo from a like clause to an equal clause

[CORE-221] - Improvements to the queuing process when running a query

[CORE-229] - Provide updated JDBC drivers used by Oracle, PostgreSQL, and SQL Server

New Features

[CORE-218] - New web service to retrieve the db lookup settings in the configuration files

[CORE-226] - New parameter to use temp table constraint instead of 'WITH' clause

[CORE-227] - Add ability to send parameters with string based variables as varchar instead of nvarchar

Bug Fixes

[CORE-151] - Modifiers associated to inactive terms appear as active in hierarchical tree

[CORE-184] - Generated SQL is not escaping single quotes correctly if a space exists between multiple values in C_DIMCODE

[CORE-206] - Query failing to time out into processing queue

[CORE-208] - qt_privilege primary key

[CORE-211] - Some large queries are remaining in the medium queue

[CORE-220] - SqlServer Age at Visit incorrect for 24, 80, 81 and 89

[CORE-230] - SQL Server: Issue with non-clustered index on temp tables

Documentation

 [CORE-188] - Unable to change AGG_SERVICE_ACCOUNT password

Change Summary - i2b2 Web Client Software - Release 1.7.08

Improvements

 [WEBCLIENT-133] - Restrict ability to add Date Constraint if a panel contains any age concepts. [WEBCLIENT-192] - Improvements to queued queries in status window

New Features

 [WEBCLIENT-191] - ADMIN: Add the ability to view DB_LOOKUP settings for each cell [WEBCLIENT-198] - Parameters/Configurations for Web Client

Bug Fixes

[WEBCLIENT-98] - Updating the "Annotate" option is not reflecting on mouse hover

[WEBCLIENT-157] - Concept codes are displayed in tooltip even when the option is not selected

[WEBCLIENT-160] - Previous query panel right click menu is not not functional under Find tab and menu option display is persistant once displayed

[WEBCLIENT-161] - Max queries option under Previous queriesl/ontology terms panel allowing non integer and blank values

[WEBCLIENT-170] - Query run without selecting any run option is putting the query in processing queue

[WEBCLIENT-171] - query run with long name( more than 42 characters) is resulting in query time out and with larger number is giving sql error

[WEBCLIENT-175] - Group buttons at bottom of Query Tool will sometimes "disappear" after Printing the Query Report

[WEBCLIENT-180] - Set Modifier Value is not always an option when adding a previous query to the Query Tool

[WEBCLIENT-181] - Web Client doesn't fully logout when logging out after the timeout message

[WEBCLIENT-184] - "Not" does not appear if Group 4 or greater is excluded

[WEBCLIENT-189] - Modifiers repeat when prompted to increase number of terms in web client

[WEBCLIENT-190] - Modifiers associated to inactive terms appear as active in hierarchical tree

[WEBCLIENT-193] - Admin appears to crash when clicking on DB-Lookup for IM cell

[WEBCLIENT-195] - Fix names and fields that display on each of the new DBLookup pages

[WEBCLIENT-197] - New date constraint warning appears even if demographics are not in panel

[WEBCLIENT-199] - db_lookup

Change Summary - i2b2 Community Plugins - Release 1.7.08

Bug Fixes

 [PLUGINS-17] - Plugins manifest is pointing to the wrong URL

Improvement / New Feature Details

View and Update the DB_LOOKUP Tables

JIRA ISSUES:

      [CORE-218] - New web service to retrieve the db lookup settings in the configuration files

      [WEBCLIENT-191] - ADMIN: Add the ability to view DB_LOOKUP settings for each cell

Release 1.7.08 added the ability to view current database connections defined in the DB_LOOKUP tables for each i2b2 cells. Administrators can also edit existing values and add new entries into the tables. This new feature resides within the i2b2 Admin Module. The DB_LOOKUP tables are specific to each i2b2 cell. To access the list of values in a specific cell you need to expand Manage Cells in the Navigation Tree on the left of the page. Then select the cell to expand further, once this is done you will see DB-Lookup as an option. Clicking on DB-Lookup will display the DBLookup List page. This page will display all the values in a table format.

The following screen shot shows all the entries in the CRC_DB_LOOKUP table.

To add a new entry into the DB_LOOKUP table simply click on the Add New DBLookup button that appears above the table of existing values. The page will be updated to a form with fields to capture the information to be stored in the DB_LOOKUP table.

To edit an existing entry, click on its Name located in the Navigation Tree on the left. The page will be updated to show the values currently filed in the DB_LOOKUP table. Make any changes and click on Save to save your edits.

Improvements to the Processing of Queueing Queries

JIRA ISSUES:

      [CORE-221] - Improvements to the queuing process when running a query

      [WEBCLIENT-192] - Improvements to queued queries in status window

In the i2b2, there are three queues a query may be placed into when it is run. The length of time a query waits in each queue is defined in the crc.properties file.

1. Small Queue
2. Medium Queue 3. Large Queue

In the Web Client, the status of a query can be seen in Previous Queries. The status would be PROCESSING, ERROR, or COMPLETED. None of these statuses would provide information on which queue the query was in. Database administrators would have to view the query in the QT_QUERY_INSTANCE table to see the queue information. The statuses and queue information were often ambiguous which would make it challenging to trouble shoot any issues.

To address this issue, new statuses have been added in Release 1.7.08. These new statuses provide users with additional information that accurately reflects the current status and location of the query. The new statuses are:

QUEUED ERROR COMPLETED PROCESSING SMALL_QUEUE MEDIUM_QUEUE LARGE_QUEUE MEDIUM_QUEUE_RUNNING LARGE_QUEUE_RUNNING RUNNING

In addition to updating the status of queries, an additional feature was added to the Web Client that makes these statuses visible to users.

The query status can be seen in Previous Queries as well as in Show Query Status.

SQL Server: Option to Improve Query Performance

JIRA ISSUES: [CORE-226] - New parameter to use temp table constraint instead of 'WITH' clause

Large data warehouses that contain broad and deep ontologies run the risk of CRC queries having a slow response time. In this release (1.7.08) a new parameter has been added to the crc.properties file. This new parameter allows a site to use a temp table instead of a 'WITH' clause when running a CRC query. In some environments, using a temp table allows the query to run more efficiently and process the request faster.

Parameter Name: edu.harvard.i2b2.crc.setfinderquery.constraintlogic

Located in: crc.properties file Behavior:

Value	Behavior
TEMP or TEMPTABLES	Temp tables will be used when building queries.
WITH	Current query logic is used

If the parameter is missing from the crc.properties file, the system will current query logic (WITH clause).

Important This change only affects SQL Server databases. Both PostgreSQL and Oracle do not have the capabilities of using temp tables. They will continue to use the WITH clause.

Date Constraint Improvements

JIRA ISSUES: [WEBCLIENT-133] - Restrict ability to add Date Constraint if a panel contains any age concepts.

In the i2b2, the CRC will use the START_DATE in the OBSERVATION_FACT table when running a query with a date constraint defined on a panel. This can present a problem if at least one of the items in the panel is an age concept and the patient demographics are stored in the PATIENT_DIMENSION table. The problem is ages that are stored in the PATIENT_DIMENSION table will not have a START_DATE and therefore the date constraint is not valid.

General i2b2 users do not know whether or not an age has a start date and if they select a date constraint their query may not return the expected results. This becomes a bigger issue when you are using the i2b2 in a larger network in which some sites may store it in the PATIENT_DIMENSION and others in the OBSERVATION_FACT. This scenario will definitely result in misleading results and the user will be unaware of the discrepancy.

To avoid any confusion or misleading results, users can no longer add a date constraint if at least one item in the panel is an age concept. The following message will appear when attempting to set a date constraint on a panel with an age concept: Date constraints are not allowed for age related concepts. This panel contains at least one age related concepts, therefore a date constraint can not be set for this panel.”

Web Client Configurations

JIRA ISSUES: [ WEBCLIENT-198] - Parameters/Configurations for Web Client

In Release 1.7.08, a new configuration file has been added to the i2b2 Web Client. This file allows site administrators to customize the text on the login screens, default user id and password values, as well as how obfuscated results display in the i2b2 Web Client.

       File Name: i2b2_ui_config.js        File Location: /webclient/js-i2b2/

Parameter		Description	Default Value
titleLogoSrc		Logo that appears in toolbar when logged into the i2b2 Web Client.	"assets/images/title.gif"
loginHeaderText		Text in the header bar of the login box	"i2b2 Login"
loginUsernameText		Text for the username input of the login box.	"Username:"
loginDefaultUsername		Default text inside the username input.	"demo"
loginPasswordText		Text for the password input of the login box.	"Password:"
loginDefaultPassword		Default text inside the password input.	"demouser"
loginHostText		Text for the PM cell dropdown of the login box.	"i2b2 Host:"
obfuscatedDisplayNumber		The number to display after the plus/minus for obfuscated results. Please see the important note at end of this table.	3
useFloorThreshold		If true, any result below floorThresholdNumber shows as '{floorThresholdText} {floorThresholdNumber}' If false, floor threshold will not be used when displaying values in the i2b2 Web Client.	false
floorThresholdNumber		Threshold for the low number of results	10
floorThresholdText		Text that is prefixed before {floorThresholdNumber} (include trailing space)	"Less Than "
	Important The calculation for the real obfuscation value continues to be controlled by the server and is based on the value defined in the CRC properties file. The obfuscatedDisplayNumber parameter in the i2b2_ui_config.js simply defines what number to display to the user when viewing the query results.

SQL Server: New Connection Parameter to Pass in String Based Variables

JIRA ISSUES: [CORE-227] - Add ability to send parameters with string based variables as varchar instead of nvarchar

Prior to release 1.7.08, parameters are sent in as Unicode (nvarchar) instead of varchar. SQL Server then has to explicitly convert the nvarchar to varchar in the query. The effect is that SQL Server optimizer may have to use an index scan instead of an index seek (which is faster).

To address this issue, we have added a new connection parameter to be used when i2b2 uses PreparedStatements to pass in string based variables in SQL Server. The following connection parameter is to be added to the datasource definition.

Connection Parameter: connection-property name=”sendStringParametersAsUnicode” Added To: datasource definition Behavior:

Value	Behavior
false	String based variable will be sent as varchar
true	Current logic is used; String based variable will be sent in Unicode (nvarchar)

Example:        <connection-property name="sendStringParametersAsUnicode" >false</connection-property>

Updated JDBC Drivers

JIRA ISSUES: [CORE-229] - Provide updated JDBC drivers used by Oracle, PostgreSQL, and SQL Server

Included in release 1.7.08 are updated JDBC drivers for Oracle, PostgreSQL and SQL Server. The new version of JDBC drivers are optional and will not be installed automatically.

Important Sites that choose to upgrade their JDBC drivers will be required to also updated the datasource files for all of their cells.

Information on Updating Drivers

This section contains some general information and key points to keep in mind when updating your JDBC drivers.

Location of JDBC Jar files

Your current JDBC jar files reside in the following directories:

1. ${jboss.home}/standalone/deployments/${axis2.war.name}/WEB-INF/lib
2. ${jboss.home}/standalone/deployments

New Version of JDBC

There are three new jar files, one for each type of supported databases.

1. Oracle = ojdbc7.jar
2. PostgreSQL = postgresql-9.4-1209.jar
3. SQL Server = sqljdbc42.jar

Update Existing i2b2 Instance

A script to deploy the new jar files has been included in the 1.7.08 Release. Once you have updated your server with the latest code you can run one of the following commands to deploy the new jdbc jar files:

Linux Command

      ant copy_new_jdbc_jar

Windows Command

      %ANT_HOME%\bin\ant.bat copy_new_jdbc_jar

Warning If you choose to install the new JDBC jar files you also need to update your datasource files with the new driver information. This needs to be done for each cell in the i2b2 hive.

 

Licensing

The i2b2 source code is licensed under the i2b2 Software License 2.1. This includes but is not limited to all code in the edu.harvard.i2b2.* package namespace.

Trademarks

Microsoft, Windows, Windows 7, Windows Server 2003 and 2008 are either registered trademarks or trademarks of Microsoft Corporation in the United States and / or other countries.

Mac OS is a registered trademark of Apple Inc.

Eclipse Galileo is a registered trademark of the Eclipse Foundation, Inc.

All other trademarks are the property of their respective owners.

References

1. Original document (for all releases)  https://www.i2b2.org/software/releaseNotes_current.pdf