Understanding the Components of XNAT
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.
Overview of XNAT Components
A standard XNAT installation consists of a WAR file that consists of several components that provide core functionality and allow extensibility.
XNAT Server
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.
Tomcat Settings
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.
Tomcat Folders
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/tomcat7XNAT Webapp Location
The 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".)
nginx Proxy
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:
- A file for your XNAT instance in
/etc/nginx/sites-available - A folder for your XNAT instance in
/etc/nginx/sites-enabled
If this is not the case, see this documentation on enabling your nginx proxy.
XNAT File System Structure
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.
XNAT_HOME Directory
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. |
XNAT File System Directories
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.
XNAT Resource Management
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 Database
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:
- XFT tables are generated to store XNAT experiment data; table structures are determined by XML Schema Documents (XSD's), which are used to define datatype fields and parameters
- Hibernate tables are generated to store dynamic system configuration data, including all site Admin UI preferences
- "Manual" tables are generated to store all other types of system data, including stored XNAT searches and caches for performance improvement
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.
XNAT Search Engine
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
XNAT User Interface
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.
User Authentication
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.
Connecting to PACS Systems and other DICOM AEs
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.
DICOM Anonymization and Archiving
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.
Data Processing Services
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.
XNAT Container Service
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.
XNAT Pipeline Engine
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.
Image Viewing and Annotation
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
XNAT Event Service & Automation
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.
XNAT API
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
Adding On To XNAT
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.
Installing XNAT Plugins
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.