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
Highlights of New Features
Major Query Status Redesign
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.
Expanded Admin Tool - Administration & Configuration Tool
The Admin Tool was enhanced with new features for user account management, authentication configuration, and project parameter management.
New Monitor Dashboard - Activity & Usage Monitoring Tool
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. 
Improvements to the Login UI
The i2b2 login now includes configurable messaging, password visibility toggle, and improved styling.
New Web Client Configurations
CSS has been centralized to make branding and customizations easier and there are new options to customize the position and behavior of tabs.
Detailed Documentation on New Features
Major Query Status Redesign
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.
Default Visualizations
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. 
Optional Visualizations
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
.)
Mapping Visualizations to Breakdowns
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>
Creating New Breakdown Visualizations
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.
Configuring the Query Report
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.
Displaying Query Status in a Separate Tab
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+.
Expanded Admin Tool - Details shared previously
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
New Monitor Dashboard - Details shared previously
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
Improvements to the Login UI
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
New Web Client Configurations
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
Security Related Changes
Web Client Changes
- Fixed a script injection-related origin-host validation issue in i2b2-loader.js for plugins
Server-Side Changes
MGB team to add, if desired.
Bug Fixes
Web Client Changes
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
Server-Side Changes
MGB Team to Add if desired
Additional Miscellaneous Changes
Web Client Changes
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
Server-Side Changes
MGB Team to Add if desired
