XNAT 1.10.0 Release Notes
The XNAT 1.10.0 release is an update to the core platform technology on multiple fronts: Updating the Java version from version 8 to 21, updating dcm4che from version 2 to 5, and related updates to core dependencies and the test suite to validate functionality.
A note on plugin compatibility:
This platform update does not inherently require corresponding updates to all plugins, as plugins that are compiled in JDK8 are still found to run in XNAT 1.10.0. However, some plugin updates were required for other compatibility or performance reasons, including:
DICOM Query-Retrieve (DQR) Plugin: version 3.0.0 or higher is required
Distributed Events Plugin: version 2.0.0 or higher is required (for multi-node XNATs only)
Multifactor Authentication (MFA) Plugin: version 1.6.0 or higher is required
XNAT-OHIF Viewer Plugin: version 3.8.0 or higher is required
XNAT 1.10.0 also includes a major new feature: Dynamic Data Types, which allows for the creation of new experiment and assessor types without the development or installation of a new plugin, or even a tomcat restart.
Java 21 Platform Update
Previous releases of XNAT going back to 1.8.0 have been on JDK8, which is still supported through 2030 but has stopped receiving public updates. With this release, we moved XNAT to the latest LTS version of Java, which at the time of development was JDK21.
This update to the XNAT platform requires an Apache Tomcat 9 instance that runs Java 21. However, as mentioned in the note above, updating XNAT to Java 21 does not necessarily require all plugins to be updated immediately as well. Plugin developers should consult our updates to dependencies – notably dcm4che2 → dcm4che5 – to determine whether their own code needs updating for compatibility.
Updating XNAT to Java21 could be described as only a 20% code effort, with the remaining 80% of our time spent on testing and validation. XNAT’s automated test framework has been updated and expanded, covering backend functionality with REST tests and front-end validation with a combination of significant hands-on testing as well as automated tests migrated from Selenium and Katalon to Playwright.
This is the first major architectural change toward a system modernization that should eventually land with XNAT running on Tomcat 11. However, that will have further-reaching ramifications, with impacts to the REST API and the construction of the UI.
Related Tickets:
Update dcm4che from version 2 to version 5
XNAT’s ability to ingest, search, and parse DICOM data depends on the dcm4che library. For as long as XNAT was tied to JDK8 (or any version lower than JDK11), we were also tied to the legacy dcm4che2 version of this library. The update to dcm4che5 (which is admittedly oddly numbered, as it is considered their third-generation release) takes advantage of efficiencies available in modern versions of Java, and also offers increased support for VRs that dcm4che2 did not handle.
This update also impacts the mizer and dicom-edit libraries, but does not (yet) spell the end of support for XNAT’s legacy dicom-edit4 language.
Perhaps the thorniest ticket in this area is the restored support for ingesting very large (> 2GB) DICOM files, which has not been supported since pixel anonymization was added to the dicom-edit library in XNAT 1.8.10. This ability is partially restored – pixel anonymization still cannot accept encapsulated files that are larger than 2GB. However, imports without anonymization will succeed, and very large unencapsulated files can have JPEG2000Lossless compression applied to encapsulate those files, allowing for anonymization.
Related Tickets:
DE-142: (Epic) Update DicomEdit and Mizer to dcm4che5
XNAT-7936: (Epic) Update DICOM handling in XNAT via dcm4che5
XNAT-7840: XNAT cannot accept files where length of pixel data >= 2GB
XNAT-8645: Provide an option to encapsulate very large DICOM files
Known Issues on Release:
XNAT-8737: XNAT cannot perform anonymization on encapsulated files larger than 2GB
Allow Dynamic Creation of Data Types
One of XNAT’s core principles is extensibility, and the platform has always supported an extensible data model, allowing developers to create new clinical or imaging data types that support their research needs. However, until now, this required significant developer effort and understanding of how XNAT’s XML Schema Definition.
The introduction of Dynamic Datatypes allows site administrators to create new schema entries on the fly, pair them with a custom form to define searchable fields, and make them immediately available to all users on the site. See Documentation: Adding a Dynamic Data Type.
Additionally, several new capabilities have been added to the Administer Data Types user interface, allowing site admins to manage searchable fields, listing displays, view XSDs, and more. See Documentation: Managing Data Types in XNAT.
Related Tickets:
XNAT-8664: (Epic) Enable Dynamic Data Types
When working with Dynamic Data Types in a multi-node XNAT environment, please ensure that you are running the latest version of the dist-events plugin to ensure proper propagation of CRUD events related to these data types.
Other Improvements and Bugfixes
A series of improvements were included in this release largely targeting large XNAT systems that support high volumes of data and large processing job batches.
Improvements to DICOM Importing and Archiving
XNAT-8341: Ensure custom routing on imports (via DQR) persists after Tomcat restart
XNAT-8542: Ensure consistent scan labeling when importing and merging multiple scans with the same scan ID
XNAT-8649: Improve efficiency of large scale compressed uploads by writing files directly to the XNAT cache space
XNAT-8701: Add support for importing Breast Tomography SOP Class as scans and sessions of MG modality
XNAT-8716: Allow Direct Archive to append & overwrite existing files when specified
Improved Efficiency and Accuracy of Internal Queries and Counts
XNAT-8629: Refactor thread locking to support concurrent uploads on multiple threads
XNAT-8655: Improve efficiency of preparing data for use by containers and notebooks
XNAT-8659: Slow DB query caused high Postgres load
XNAT-8673: Fix performance issue in DefaultGroupsAndPermissionsCache
XNAT-8720: Ensure that SHARE and MOVE actions update counts for data listings
XNAT-8724: Improve thread safety and accuracy of counts
XNAT-8725: Event handling, caching, and locking efficiency for counts
UI / Behavioral Improvements
XNAT-8578: Rationalize color usage in XNAT CSS for theme development
XNAT-8634: Fix bug in sharing UI meant to prevent orphaned shared experiments
XNAT-8641: Remove extraneous 'q' from Review & Archive page
XNAT-8642: Fix bug causing sitewide listings to be empty after restart
XNAT-8669: Ensure loading of HTML resources from concurrent threads
XNAT-8670: Ensure consistent loading of custom report pages via search & API loads
XNAT-8715: Revert a change in XNAT 1.9.3 that slowed down page load times of the Administer Users page. Make display of ALL_DATA_ACCESS and ADMIN permissions available on click
XNAT-8722: Fix bug in catalog construction for downloads when files have non-ASCII characters
Ensure Modern Tomcat Support
XNAT-8723: Fix bug affecting JSP page display in Tomcat version 9.0.116
Demotion of Legacy Features
Legacy features in XNAT such as Series Import Filters (replaced by DicomEdit reject[] statements) and Automation scripts (replaced by Event Service) are being demoted but not fully removed from the XNAT platform.