Administering XNAT

Monitoring XNAT

Advanced Topics

[Edit Nav]

Understanding the XNAT File System

The XNAT file system can be a bit confusing to the novice user. In this document, we will clarify the role of the different folders and file structures.

XNAT Installation Directory

The XNAT installation directory is created by you (the site administrator) when you extract the XNAT zip or checkout the code from Mercurial. The initial installation directory contains the areas of interest


The maven.xml is a the file which governs the installation (and update) of XNAT. It includes the instructions for how the webapp should be prepared. Generally, you should not need to modify (or even open) this file. However, XNAT developers may need to tweak the logic from time to time. Modifications to this file should be contributed back to the XNAT project (otherwise the changes may be overwritten when the installation is updated).


The build.properties file is located in the root directory of the XDAT installation. It has several key variables which must be customized before the installation process can continue.
  • maven.appserver.home : This defines the directory where your installation of Tomcat is located.
  • xdat.project.name : This defines the name of your project. It will become the name of your webapp as well.
  • xdat.project.template : The xdat.project.template variable decides the template your new project will use. If the 'xnat' template is specified, then additional screens and classes will be provided for use in your webapp, and the xnat.xsd will be included by default.
  • xdat.project.db.name : This defines the name of your database.
  • xdat.project.db.driver : This defines the name of the database driver. Currently, org.postgresql.Driver is the only option.
  • xdat.project.db.connection.string : This is the connection string which will be used to connect to your database.
  • xdat.project.db.user : This is the username to be used when connecting to your database.
  • xdat.project.db.password : This is the password to be used when connecting to your database.
  • xdat.archive.location : Root directory which contains the image data of all the projects, subjects, & sessions. This path will be stored in the database and can be configured through the web interface.
  • xdat.prearchive.location : Directory into which the imaging session data will be stored until its archived. This path will be stored in the database and can be configured through the web interface.
  • xdat.cache.location : Directory into which the imaging session data will be cached, and deleted data will be placed. This path will be stored in the database and can be configured through the web interface.
  • xdat.admin_email : Email address which should be used for error messages and return addresses of system emails. This path will be stored in the database and can be configured through the web interface.
  • xdat.url : Url of the local installation. This should match the URL which users will use to access your site. This path will be stored in the database and can be configured through the web interface.


This is the default content provided by XNAT. It includes the schema, HTML files, Java Files, etc. This is the guts for the standard XNAT web site. This content is provided by XNAT and should only be modified by XNAT developers.


The projects directory is populated by the setup.sh script. It's initial content is contained in the plugin-resources folder or auto-generated. The projects folder is owned by you (the site administrator). This is the place where you should place your customizations. If your java and velocity modifications are placed here, then they shouldn't be overwritten.

The project has several key files/directories.


The InstanceSettings.xml is critical to the functioning of XDAT. The InstanceSettings.xml file specifies the locations of schemas, and the settings for the database connection. This Instance Settings file is configured by the xdat:setup when the file paths are set and the build.properties are added. The configured InstanceSettings.xml docs are placed in the DEPLOYMENTS/PROJECT_NAME/InstanceSettings.xml and the DEPLOYMENTS/PROJECT_NAME/src/InstanceSettings.xml directory. The DEPLOYMENTS/PROJECT_NAME/InstanceSettings.xml controls the command prompt tools. The DEPLOYMENTS/PROJECT_NAME/src/InstanceSettings.xml controls the generated web application. Any changes made to the PROJECTS/PROJECT_NAME/InstanceSettings.xml will be made to the DEPLOYMENT files by the xdat:setup task or the xdat:update task.


This directory contains all of the schemas which can be used by the project. It will be copied into the DEPLOYMENTS directory by the setup or update scripts and then into the webapp.


This file contains the sql to create the database and is generated by the setup or update scripts.


This file contains the log4j settings for XDAT’s use at the command line. (It does not effect the webapp.) It can be modified per log4j’s instructions.


This file is the default setup for the XDAT security model.


This directory contains all of the java classes generated by the setup or update scripts, as well as any custom classes which you define. Custom classes should be placed in the org/apache/turbine/… directories. The files generated/provided by XDAT will be placed in the org/nrg/… directories.

All of the classes in these directories will be compiled and placed in the webapp by the ‘xdat:deploy’ or 'xdat:war' script.
  • Java Report and Edit Screen Classes
    XDAT uses Jakarta Turbine to manage the web application. Turbine relies on the use of Action and Screen classes to manage web communication. The screen classes are displayed using two files, the Java class (Screen) and a Velocity macro (template). XDAT generates Screen classes and Velocity templates for displaying your main data types. Whereas the generated Velocity template often needs to be customized, the generated java classes are usually sufficient for basic display needs. The generated java classes are placed in the org/nrg/xdat/turbine/modules/screens directory/package. If you need to customize these classes, you should extend the generated classes with custom class placed in the org/apache/turbine/app/PROJECT_NAME/modules/screens.

  • The placement of files in these directories is very important. XDAT configures Turbine (the web app framework) to look in certain packages for classes. First, it looks in the org/apache/turbine/… directory. This is where customized classes should be placed (guaranteeing that they will be found by Turbine first). Second, Turbine will look in the org/nrg/xnat/… directories. This is the location where provided XNAT classes will be placed by XDAT. Finally, Turbine will look in org/nrg/xdat/… where generated classes are placed.
  • For more information on customizing reports...

  • OM Java Classes (Business Objects)
    The org/nrg/xdat/om/… directories contain the classes which implement the org.nrg.xft.ItemI interface for each complex type in the loaded schemas. These java classes are available for your use throughout your application. You should put all custom methods in the classes at the om level. They will automatically be instantiated and loaded when XDAT reports are called. The sub-packages org/nrg/xdat/om/base and org/nrg/xdat/om/base/auto should not be edited, as they could be overwritten.


This directory contains the images which will be used in your webapp. Place any additional images in this directory. All of these images will be placed in the webapp by the ‘xdat:deploy’ script.



These directories contain the velocity macros which will be used by Turbine to create your web pages. The macros are divided into three directories (similar to the java classes). XDAT configures Turbine to look for templates in a certain order. First, it will look in the templates directory. This is where any customized macros should be placed. Second, it will look in the xnat-templates directory (where pre-built macros for XNAT are provided). Finally, it will look in the xdat-templates directory (where XDAT places generated macros).
The setup or update step will create velocity macros IN THE FOLDER for all complex types which have a corresponding root element in the schemas. For example, the XNAT schema has a complex type xnat:mrSessionData with the associated root element MRSession
<xs:element name="MRSession" type="xnat:mrSessionData"/>.
Thus, the setup or update step will create a velocity macro for the MRSession root element.
The generated macros will contain every field which is possible to show in for the corresponding complex type. This is usually excessive. To customize the macro, copy it from the PROJECT_NAME/src/xdat-templates to the PROJECT_NAME/src/templates. There you can make any desired changes, and they will not be overwritten if the ‘xdat:update’ script is run.


All of the files in this directory will be copied into the DEPLOYMENTS/PROJECT_NAME/src/conf folder and, in turn, copied into the webapps/WEB-INF/conf folder for use by the website. If you need to customize the logging behavior of XNAT (log4j.properties), you should copy the file here and modify it.


The deployments directory has several key files/directories.


This is the directory where logs from the command line tools will be generated by default. (Configurable in the PROJECT_NAME/log4j.properties file)


This contains the settings for the generated webapp. The only file you should need to edit is the log4j.properties which controls logging in the webapp. All of these files will be copied into the webapp (WAR) during the setup or update script. If you need to modify the log4j.properties file, it should be copyied to PROJECTS/PROJECT_NAME/src/conf.


This directory contains documents which specify all of the available fields in each complex type as well as the database columns which they map to. This document is a useful resource when building display documents.


This is the provided folder for output files. By default, the command line tools of Search and Browse will place documents into this directory (unless a different directory is specified).