open source imaging informatics
open source imaging informatics
This document is meant to be an introduction to the logical architecture of XNAT – how it is set up, how it manages data and permissions, and how it allows you to customize it. This is meant for an XNAT Administrator audience, who should be comfortable working with the UI and administering the XNAT web server via the command line. There is greater depth to be found in the XNAT Developer Documentation.
A standard XNAT installation consists of a WAR file that consists of several components that provide core functionality and allow extensibility.
XNAT is a Java-based web application that runs on an Apache Tomcat web server. As of XNAT 1.8, the standard installation runs on Tomcat 7, but you can modify XNAT for Tomcat 8 fairly easily. An XNAT installation includes several Java libraries that enable core functionality such as Spring, Turbine, Reactor, and Hibernate.
If you need to change your Tomcat configuration, those files are located at: /etc/default/tomcat7. This is useful for setting JAVA_OPTS settings to ensure that your application runs smoothly. See: Configuring Tomcat To Avoid Errors.
The xnat file system user should have full ownership of each of these folders to ensure proper web app functioning.
/var/lib/tomcat7
/etc/tomcat7
/var/log/tomcat7
/var/cache/tomcat7The XNAT web application is installed at /var/lib/tomcat7/webapps. By default, the WAR file should be named "ROOT.war" to install the webapp in your server's root directory. (You can also name it something else, such as "xnat.war" to install the webapp at "https://{server}/xnat".)
For a variety of reasons, it's a very good idea to configure a front-end proxy for your Tomcat server (if you want to understand why, ask a member of the XNAT team or have a look at the docs about configuring nginx as a reverse proxy). The xnatstack box is configured with the nginx service for this purpose.
If this is set up properly, you should have the following in your file system:
/etc/nginx/sites-available/etc/nginx/sites-enabledIf this is not the case, see this documentation on enabling your nginx proxy.
During XNAT Installation, a series of file system paths are set up on Tomcat and owned by the system user (here named xnat). This documentation describes the typical set of paths, though it is possible to use alternate paths as needed.
Each XNAT installation has, in its folder structure, a folder known as XNAT_HOME. In a typical installation, this is located at /data/xnat/home. XNAT installation will create a system user named xnat that has permission to read, write and execute files in this directory. If you are ssh'ed into your XNAT server and sudo as the xnat user, this will be your home directory (~/).
Many customizations that you make, such as adding plugins or enabling additional configurations, will take place in the subfolders located here:
| Folder Name | Standard Location | Purpose |
|---|---|---|
| configs/ | /data/xnat/home/configs | Allows you to store additional configurations that will be used directly by XNAT. Configurations in this folder will overwrite any configurations specified in plugins. |
| logs/ | /data/xnat/home/logs | Location for all logs created by the web application. Useful for debugging purposes. |
| plugins/ | /data/xnat/home/plugins | The place to install XNAT plugin JAR files. |
| themes/ | /data/xnat/home/themes | |
| work/ | /data/xnat/home/work | This is a working directory which can be used by multiple processes. |
There are dedicated directories in place in the XNAT web app that are used for file storage. The locations of these can be customized in the UI in your first time configuration, which can be useful if you intend on handling large amounts of data. It is possible, but not recommended, to change these locations at a later date.
| Folder Name | Standard Location | Purpose |
|---|---|---|
| archive | /data/xnat/archive | The XNAT Archive is the permanent storage location for all XNAT files, such as uploaded DICOM files or project resource files. All files in this folder are catalogued in the XNAT web application, and tracked in the XNAT audit trail. For any non-clinical XNAT, take steps to prevent files with personal health information (PHI) from being stored in this location. |
| build | /data/xnat/build | This path is currently unused, but is reserved for potential future enhancements to the build process. |
| cache | /data/xnat/cache | The XNAT user cache is a place where XNAT can store user-specific files. These are often temporary files. When users or processes mark a file for deletion, XNAT does not actually delete the file. Instead, it is sent to the |
| ftp | /data/xnat/ftp | This is a reserved path for the now-deprecated XNAT FTP server. |
| prearchive | /data/xnat/prearchive | The XNAT Prearchive is an interim file storage area separate from the XNAT Archive, where uploaded files can be safely reviewed for PHI. It is common for ongoing studies to upload image sessions to the Prearchive rather than directly to the archive. |
| pipeline | /data/xnat/pipeline | This is a reserved path that is used when installing the XNAT Pipeline Engine |
For more information about advanced file system management, see the XNAT IT Operations documentation.
Files that are stored in the XNAT Archive are stored as resource collections and attached to various data objects in XNAT. For example, imported DICOM scan files are stored as scan-level resources, where that scan is associated with an image session for a subject in a project. Individual files in each collection are catalogued, so that they can be retrieved by XNAT's file download service. However, they are not indexed for search capabilities. Learn more about resource management: Managing Resource Files in XNAT
XNAT uses the PostgreSQL database to store all of its persistent data that's not stored in files on the local storage device. The XNAT web application requires a dedicated user and database to be set up. This is a fairly straightforward process. See: Configuring PostgreSQL for XNAT.
There are three main types of tables that XNAT creates in PostgreSQL:
See Understanding the XNAT Data Model for a more thorough understanding of how XNAT indexes and stores experiment data.
XNAT plugins can add new datatype definitions by including new XSD files. However, once installed, these plugins should not be removed from your XNAT server to avoid PostgreSQL issues.
The XNAT search engine is built directly on top of XFT, which is a parsing of the project- and experiment-based XNAT data model defined in the XSD. The search engine queries indexed XFT tables within PostgreSQL, and is able to join multiple data tables together to offer comparative searches. The UI offers ways to allow users to simply request data (i.e. "Show me all MR Sessions in Project A"), and this type of request is translated into a XML document that specifies exactly what schemas to parse, and which fields to retrieve.
The XNAT Search engine receives this XML document and queries the PostgreSQL database, and returns results in a rectangular format, which is normally presented as a data table but can also be exported as a CSV file. (It is possible to run advanced SQL queries directly against the XNAT database to perform advanced reporting tasks. However, this requires knowledge of how XNAT data tables are structured and how they can be joined.)
See Using the Standard Search and Using the Advanced Search for reference.
XML Search Definitions can be saved within the XNAT UI, and it can be useful for a complex search to be saved and shared with multiple users in your site. See: Saving a Data Table as a Stored Search
The XNAT webapp UI is powered by the Turbine library, and uses a combination of Java backing classes and Velocity templates to build the front end HTML files and serve data to them from the back end. Additional dynamic functionality is provided via the use of XNAT namespaced JavaScript functions and asynchronous calls to API endpoints tied to XNAT services. The XNAT UI can be customized using XNAT Plugins and Themes.
By default, XNAT user authentication is managed by Spring Security. Users are given access to project data through the definition of user groups. All access to XNAT data and functions, whether through the UI or the API, are secured.
See Understanding User Roles and Permissions for additional details.
It is possible to set up support for alternative authentication providers, such as LDAP or OAuth, through dedicated XNAT plugins.
XNAT has built in support to act as a DICOM SCP Receiver, which allows it to be a configurable destination to receive data that is sent from a PACS system. See Connecting XNAT to DICOM Scanners and PACS for more details.
With the release of the DICOM Query Retrieve plugin, it will be possible to set up two-way data querying and transfer from XNAT to a DICOM AE and back again.
XNAT has built-in support for DICOM Anonymization and Deidentification using the DicomEdit language to write anonymization scripts. This anonymization happens within the XNAT server during the session-building process after DICOM files are received, so it is possible to prevent PHI and PII from being stored in XNAT's archive. See DicomEdit Documentation for details.
If you are concerned about preventing PHI or PII from ever hitting your XNAT server, there are other ways of performing anonymization prior to data import.
XNAT natively supports data processing using both pipeline- and container-based workflows. Your specific XNAT installation may support either or both of these workflow types. All processing workflows are tracked using the XNAT Workflow API.
Containerized workflows have several major advantages that support reproducible science, including the ability to define and preserve precise runtime environments. XNAT launched its initial support of the Container Service with release version 1.7.3 in 2016, and has expanded its support since.
The XNAT Container Service can be enabled with the installation of the Container Service Plugin. Currently, this requires the configuration of a Docker server alongside or accessible by your XNAT server, though ongoing development is underway to support other container hosts such as Singularity that are more friendly to High Performance Computing clusters.
Executable containers are installed via Container Images with XNAT-enabled command definitions, using the Container Service Admin UI. See Getting Started with Container Service.
XML Pipeline workflows have been supported since the very early days of XNAT, and until the release of XNAT 1.8, the image archiving process had a hard-coded dependency on a properly installed XNAT Pipeline Engine. (See Installing the Pipeline Engine.)
XNAT Pipelines are installed and enabled via a combination of system administration via SSH and configuration via the UI. See Installing Pipelines in XNAT.
As of XNAT 1.8, no DICOM image viewer comes preinstalled in your XNAT system. We highly recommend installing the XNAT OHIF Viewer Plugin, which includes support for drawing annotations and regions of interest on scan data and saving those into ROI Collections that can be stored alongside your image session data in XNAT. The XNAT OHIF Viewer also has integrations with AI-assisted Image Annotation tools powered by NVIDIA Clara.
It is also possible to install the legacy XNAT Image Viewer, which has a much smaller feature set but does support viewing NIFTI images. See Legacy XNAT Image Viewer Plugin
The XNAT Event Service is based on the Spring and Reactor Java libraries installed in the XNAT server, and allows site administrators to set up actions that can be run (i.e. "Run a container to convert DICOM to NIFTI") based on event triggers such as "Scan Archived". See XNAT Event Service Documentation for more details.
A large number of core XNAT services have corresponding API endpoints that allow access to those services – for retrieving, storing, and manipulating data objects, or triggering utility functions. A full listing of XNAT API is documented here: XNAT REST API Directory.
Modern XNAT API development (i.e. endpoints developed since the introduction of XNAT 1.7) are documented within the XNAT server itself, using Swagger. The Swagger UI is accessible within your XNAT (after authentication) at https://{serverAddress}/xapi/swagger-ui.html
The primary recommended method for extending XNAT functionality is via plugins. While it is possible to customize your core XNAT webapp files, we do not recommend this as it creates problems upgrading to future XNAT releases.
The full documentation for installing and managing XNAT plugins is here: Deploying Plugins in XNAT. As referenced above, the standard location of your plugins folder is here: /data/xnat/home/plugins.
For more on working with or developing new XNAT plugins, see this guide: Working with XNAT Plugins.
XNAT is an open source project produced by NRG at the Washington University School of Medicine | NRG Home
Contributions to the XNAT Documentation site are licensed under a Creative Commons Attribution 3.0 Unported License. 