1.8.3 Web Client Enhancements
1.8.3 Web Client Enhancements
Table of Contents
Highlights of New Features2
Major Query Status Redesign2
Expanded Admin Tool - Administration & Configuration Tool2
New Monitor Dashboard - Activity & Usage Monitoring Tool3
Improvements to the Login UI3
New Web Client Configurations4
Detailed Documentation on New Features4
Major Query Status Redesign4
Default Visualizations4
Optional Visualizations9
Mapping Visualizations to Breakdowns12
Creating New Breakdown Visualizations12
Configuring the Query Report12
Displaying Query Status in a Separate Tab13
Expanded Admin Tool - Details shared previously14
New Monitor Dashboard - Details shared previously14
Improvements to the Login UI15
New Web Client Configurations16
Security Related Changes16
Web Client Changes16
Server-Side Changes16
Bug Fixes16
Web Client Changes16
Server-Side Changes17
Additional Miscellaneous Changes18
Web Client Changes18
Server-Side Changes18
Query Status was redesigned to be modular, where one or more data visualizations can be mapped to each query breakdown. These range from simple bar charts and pie charts to complex interactive spatiotemporal visualizations and data download options.
The Admin Tool was enhanced with new features for user account management, authentication configuration, and project parameter management.
The new Monitor Dashboard tool provides summaries of i2b2 user activity, such as the number of queries run per project, number of new users, number of failed login attempts, and trends over time.
The i2b2 login now includes configurable messaging, password visibility toggle, and improved styling.
CSS has been centralized to make branding and customizations easier and there are new options to customize the position and behavior of tabs.
The i2b2 web client now includes a library of modular data visualizations that can be used with Query Status. A configuration file (`/js-i2b2/cells/CRC/QueryStatus/breakdowns.json`) maps each query breakdown to one or more of these visualizations. Users can switch between different visualizations using a drop-down menu on the top-right corner of each breakdown. Query Report has also been updated to use these new visualizations.
This new feature greatly expands how breakdowns can be used in i2b2. Previously, bar charts were the only way to view query breakdowns. This limited breakdowns to a small number of categories before the charts became unreadable. By pairing custom SQL breakdowns with the appropriate visualization(s), any type of breakdown data can be returned to the web client presented to the user in different ways.
By default, i2b2 1.8.3 includes several breakdowns and mapped data visualizations. These include demographic breakdowns mapped to bar charts, pie charts, and line graphs; an NIH-style enrollment table; a table summary of the data; and an option to download the breakdown as a comma-separated values (CSV) file.
Below is the standard Bar Chart showing a drop-down menu with additional visualization options.
The Line Chart visualization is useful for breakdowns where the categories are numbers or dates, such as patient age.
The Pie Chart visualization shows the proportion of patients in each category.
The NIH Enrollment Table visualization is based on forms used by the U.S. National Institutes of Health to collect demographic breakdowns (race, ethnicity, and sex) for clinical studies.Clarification: this is expected to be enabled (visible if properly configured) in the out-of-the-box 1.8.3 web client.Yes, it should be enabled.FYI we have nowhere to test this yetThis breakdown SQL needs to be added to i2b2 back-end you are using for testing (and to the 1.8.3 release). There is also a custom SQL breakdown to replace the default age breakdown to make the age visualizations look better. The SQL for the optional breakdowns also needs to be included in 1.8.3 in a separate file.
The Table Summary displays a simple table with each breakdown group and the corresponding number of patients.
The CSV Download option, rather than displaying the breakdown within the web client, exports the data to a CSV file that can be opened in other data analysis programs.
The i2b2 1.8.3 web client includes several additional data visualizations, which by default, are not mapped to any breakdowns. The i2b2 software includes an optional database script to add new custom SQL breakdowns to the QT_QUERY_RESULT_TYPE and QT_BREAKDOWN_PATH tables. Once these have been installed, they can be mapped in the i2b2 web client file (via `js-i2b2/cells/CRC/QueryStatus/breakdowns.json`) to their corresponding visualizations.
The Table Bar Chart is similar to the Table Summary visualization, but adds a small horizontal bar chart in the rightmost column. This is useful for breakdowns with so many categories that they would not be easily readable in a standard vertical bar chart. An optional diagnosis category breakdown is included with i2b2 1.8.3 to demonstrate this new visualization. (Note that to improve performance of this breakdown, a new table is added to the database to pre-compute patients' diagnosis categories.)
The ZIP Code visualization displays the geographic location of patients matching the query. It is interactive, allowing the user to quickly zoom to different configurable levels (e.g., city, state, region); select an aggregation level (e.g., 5-digit ZIP Code, 3-digit ZIP Code, or state); and select a normalization type (e.g., actual counts - no normalization, or dividing by the total number of patients in the region). (Note that 5-digit ZIP Codes cannot be used if the underlying i2b2 data has been de-identified by removing patient ZIP Codes or replacing them with 3-digit ZIP Codes. Also, shape files have only been included in i2b2 1.8.3 for regions in the United States. Though these can be replaced with any shape file that uses the standard GeoJSON format.)
The Pathogen Timeline displays counts by month or year of COVID-19, influenza, and RSV diagnoses in the patients who match a query. These three diagnoses are included as examples in the custom SQL breakdown. However, these can be changed to any type and number of temporal values. For example, this visualization can be used with an "Encounter Timeline" breakdown that returns the number of inpatient and outpatient visits over time. The visualization also supports overlays, with data from an external file or API. This is demonstrated with an example file containing COVID-19 wastewater pathogen levels in Boston, Massachusetts, from 2020-2025. (The data were obtained from the Massachusetts Water Resources Authority wastewater tracking website, https://www.mwra.com/biobot/biobotdata.htm![]()
Once a visualization is registered to the Query Status/Report subsystem (via `/js-i2b2/cells/CRC/QueryStatus/config.json`), it can then be mapped to one or more breakdowns that can be returned from the server (via `/js-i2b2/cells/CRC/QueryStatus/breakdowns.json`).
The mapping JSON file is a simple nested dictionary with the first level being the code of the breakdown as returned from the server, and the second level being the code of one or more breakdown visualization modules that have been registered to the subsystem.
In some special instances a visualization can be created as a "Super Module" which will handle the rendering of multiple breakdown results within its individual area. Currently this is only being done to display the status of data request submissions but is an option for you if you are developing new visualization modules.
For full configuration details see the README.md file within the QueryStatus directory for the most up-to-date information. [<span style="color: #1155cc"><span class="nobr"><a href="https://github.com/hms-dbmi/i2b2v2-webclient/blob/v1.8.3/js-i2b2/cells/CRC/QueryStatus/README.md" class="external-link" rel="nofollow">https://github.com/hms-dbmi/i2b2v2-webclient/blob/v1.8.3/js-i2b2/cells/CRC/QueryStatus/README.md+<sup><img class="rendericon" src="/wiki/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></span>]
<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="2d422ce3-e273-413b-91bd-1948b1229a56"><ac:parameter ac:name="">_7xmes2ddu0ct</ac:parameter></ac:structured-macro>
When developing a new breakdown visualization all related files should be placed in its own folder within the `/js-i2b2/cells/CRC/QueryStatus` directory. Additionally, a registration entry needs to be placed within `/js-i2b2/cells/CRC/QueryStatus/config.json` so that the Query Status and Query Report subsystems are aware of your visualization module. See the extensive documentation (`README.md` files) within the Query Status subsystem's directories and other included visualization modules for examples of how to write your own module.
The Query Report subsystem exists within the `/js-i2b2/cells/CRC/QueryReport/` directory and is configured using the `ReportConfig.json` file to set which visualizations are displayed for each breakdown in the Query Report. To change or style the text on the printed report you can edit the `QueryReport.html` file within the subsystem's root directory.
In previous versions of i2b2, Query Status appears in a fixed region below Find Patients. In 1.8.3, users can now move Query Status to a separate tab to provide more space to view the breakdown visualizations. The default location for Query Status can be changed using the tab configuration file found at `/js-i2b2/i2b2_tabs.json`. The configuration file is a lightweight subset of the Item configuration options found in the Golden-Layout framework found at {+}https://golden-layout.com/docs/ItemConfig.html+![]()
Changes to the Admin Tool include:
Show the user role modal immediately after adding a user to a project
Decouple Save from navigation in project-creation subpages
Allow inline editing of AGG_SERVICE_ACCOUNT
Add Global Authentication Config management
Add validation for global auth configuration fields and dropdowns
Add LDAP configuration parameters
Apply auth configuration when creating/editing users
Add delete/hide parameter status filter on parameter tabs
Add project parameter prototype support, including:
configurable predefined parameters
predefined data types
default values
Display the database table name for parameter grids
Add a pop-out parameter value view
Include project creation date
Improve user management display
Add ability to:
view locked users
unlock users
terminate user sessions
view project-level details by expanding user rows
Move delete user into the edit-user workflow
The new Monitor Dashboard tool displays:
Active session count
Successful and failed logins over a selected interval
User/admin counts
Counts by data role
New accounts / newly assigned users over time
Total queries for a project
Queries over a selected number of days
Query activity by month
Top users by query activity
12-month query volume trend
It includes options for:
Query page with filters
Project filter with autosuggest and View/Go
Fetch dropdown filter
Query data grid
Query run details popup
SQL view action for query rows
Support for obfuscated count display
Changes to the Login user interface include:
Redesigned login screen
Added configurable login message (via `loginDefaultMessage` in `/js-i2b2/i2b2_ui_config.js` )
Added show/hide password toggle button
Added protection against repeated login clicks
Improved SSO and login button styling
Updated top-bar/logo presentation
Colors used throughout the web client have been normalized and centralized into the main CSS file `/assets/css/color-scheme.css` . The 32 CSS variables defined in this file are used throughout all sections, tabs, and subsystems of the web client.
Customization of tab position can now be done using the tab configuration file found at `/js-i2b2/i2b2_tabs.json`. A "view query" button - which switches tab focus to the Query Builder tab - has been added at the top of the Query Status page via configuration of the "Summary" visualization module in `/js-i2b2/cells/CRC/QueryStatus/config.json` using the "showQueryStatus" variable. Configuration of some web client UI options (ex. "Show Synonymous Terms ") is now possible using an i2b2 server's project parameters.
Added support for project-driven Terms UI Options
Improved handling of:
boolean parameter suggestions
multiline parameter configuration
Fixed a script injection-related origin-host validation issue in i2b2-loader.js for plugins
MGB team to add, if desired.
Monitor Dashboard
Fixed project filter/project-name display when only one datasource exists
Fixed incorrect query status display as Unknown
Fixed sorting for:
project lists
query date
run time
Fixed duplicate usernames in top-user charts
Fixed incorrect counts by data role
Fixed Y-axis behavior in low-data chart scenarios
Fixed project count display issues when filters are applied/cleared
Fixed query table and project ID display issues
Fixed deleted-query handling and error-state handling
Admin Tool
Fixed auth config values being pulled from the wrong configuration when multiple configs share a type
Fixed auth method being reset unexpectedly during user edits
Fixed hidden authorization configs appearing in user lists
Fixed project user association showing all system users instead of only project users
Fixed incorrect parameter status display
Fixed password clearing behavior for non-local auth selections
Fixed tab title/project parameter display issues
Login / UI / Core
Fixed login_fullname showing XML tags
Fixed SAML button display on the updated login screen
Fixed top-bar/dropdown layering conflicts
Fixed tab selection behavior in shared layout code
Fixed tab dropdown attachment using hardcoded titles
Fixed sanitized output handling
Fixed communicator behavior when the proxy returns non-XML responses
Fixed duplicate Ontology list behavior when using "Browse in tree"
Ontology / navigation / core plumbing
Fixed i2b2.layout.selectTab()
Fixed tab dropdowns being attached by hardcoded tab title instead of component name
Fixed ONT "Browse in tree" duplicate-list issue
Fixed ONT/project-param default handling
Fixed sanitized output issues
Fixed communicator behavior when proxy returns non-XML, so errors bubble up for higher-level handling
MGB Team to Add if desired
Shared UI / styling cleanup
Removed unused images/assets
General UI cleanup around dropdowns, buttons, and z-index conflicts
Mapping infrastructure
Added Leaflet as shared map infrastructure for map visualizations
Admin Tool state management
Refactored Admin Tool Redux state handling:
reducers migrated to createSlice
allHives reducer refactor
removed older reducer patterns in places
root reducer/store cleanup
Rebuilt Admin Tool bundle after structural changes
Query Status data/display internals
Refactored handling of obfuscation and floor-threshold display across Query Status modules into a centralized formatting function `i2b2.CRC.QueryStatus.obfuscateFloorDisplayNumber()`
Made layout/config behavior more centralized and configurable (`/js-i2b2/i2b2_tabs.json`)
ONT / shared layout usage
Refactored ONT to use the newer shared `i2b2.layout.selectTab()` function
General cleanup
Removed unused template files and commented-out code
Cleanup commits around QueryStatus and Admin Tool internals
MGB Team to Add if desired