Administering XNAT

Monitoring XNAT

Advanced Topics

[Edit Nav]

Customizing your XNAT Installation

Upon completing the quick tutorial, you will be ready to customize your XNAT implementation. This tutorial will walk you through:
  1. Adding custom data types to XNAT
  2. Customizing a listing
  3. Customizing a report

Note: The XNAT framework looks for custom code, including additional schemas, in the XNAT_HOME/projects/PROJECT directory. To make your customizations take effect, run the bin/update process from the XNAT_HOME directory. This process updates the XNAT_HOME/deployments/PROJECT directory, which will contain your customizations and XNAT-generated code to support these customizations, and deploy it all to your webapp (WAR).

Adding custom data types to XNAT

1) Create an XML Schema

The xnat application is built around a core xml schema called xnat.xsd. This schema defines the basic data types which are expected to be common to all neuroimaging projects. It includes complex types for subjects, projects, experiments, imageSessions, and sessionAssessors. We encourage sites to extend the XNAT schema to create their own data types that fit easily into the XNAT framework. Schemas not based on xnat.xsd can also be included in XNAT projects, but require additional setup.

EXAMPLE: The XNAT distribution includes a schema (ext.xsd) that extends the XNAT schema. You can use this schema to try out the instructions in this tutorial. ext.xsd includes data types that derive from the subjectAssessor and mrAssessor abstract types in xnat.xsd.

2) Add your schema to the project

Adding an additional schema to an XNAT project involves two steps: placing a copy of the schema inside the project and configuring the project's InstanceSettings.xml document.
Step 1. Copy your schema file to a subdirectory in the XNAT_HOME/projects/PROJECT/src/schemas directory. By convention, we create a subfolder (named after the schema) and place the schema in that subfolder. This seperates the content of different schemas. Mirror the structure of the other schemas in the other directories.

EXAMPLE: The ext.xsd schema has already been inserted in the appropriate place in your XNAT (XNAT_HOME/projects/xnat/src/schemas/ext/ext.xsd).

Step 2. Add an entry for the schema in the project settings document (XNAT_HOME/projects/PROJECT/InstanceSettings.xml). Schema entries are represented in <Data_Model> elements. Adding a new <Data_Model> entry should be as simple as copying and pasting an one of the <Data_Model> elements already in the document and editing the values of the file name and path attributes to point to your schema. The ordering of the data models is important. If your schema references one of the other schemas (like xnat.xsd), then it must come after the referenced schema. If you place your data model entry after the others, you should avoid any issues. The File_Location attribute should be similar to the other schemas File_Locations.
EXAMPLE: A <Data_Model> entry for the ext.xsd schema is already included in the XNAT_HOME/projects/xnat/InstanceSettings.xml. To activate it, remove the comment tags (<!-- and -->).

3) Run the update script (bin/update.sh or bin\update.bat)

Run the update script in the XNAT_HOME directory. This script will generate files for your new schema and deploy the updated project to the deployment folder.
After the update script completes, descend into the XNAT_HOME/projects/PROJECT directory and browse the files which where created. It will have added a 'display' directory in the same directory as your schema.xsd (ext.xsd). In that display directory, display.xml files will now exist for each of your root level data types. These dictate how your data types will be displayed in listings in the web application. Next, browse to the XNAT_HOME/projects/PROJECT/src/java/org/nrg/xdat/om directory. Here you will find Java classes which correspond to all of the complex types in your schema (and other schemas). These can be used in later development. Next, browse to the XNAT_HOME/projects/PROJECT/src/base-templates directory. Here you will see the generated velocity templates for your root level data types. These will be used later.

4) Update the database

The sql to update your database is in XNAT_HOME/deployments/PROJECT/sql. To update your database, run the PROJECT-update.sql file using psql or pgAdminIII.
EXAMPLE: The code to update your database is in XNAT_HOME/deployments/xnat/sql/xnat-update.sql. Execute this file on your database.

5) Re-Deploy the webapp

To finish the installation you will need to re-deploy the generated WAR to your webapp (this can be skipped if you used the -Ddeploy=true tag).
Re-start your Tomcat server and navigate to the xnat webapp on your local host (usually http://localhost:8080/PROJECT).

6) Setup XNAT security to allow access to your new data types

By default you cannot 'Browse' data types in the web application. You have to specifically, configure the access of any data types which you want to allow. You will need to configure the access settings for the pertinent data types in your schema in order to browse them through the web application.
Login to the site using the username 'admin' and the password 'admin'. This logs you in as the Admin account (use a seperate admin account if you have created one).
Proceed to the 'Data Types' section of the Administration page. Click the 'Setup Additional Data Type' link to access the Data Type Wizard.

Wizard page 1:
The drop down list contains all root-level elements from all loaded schemas which have not been previously defined for web access. Select your data type from the list. (If your data type does not appear, verify that your root-level elements are defined according to XNAT standards).
Wizard page 2:
Configure access to your data type. Whether or not the Data Type is Browsable will determine whether or not the data type is available in the Browse list in the navigation menu. For more information on security, see this.
Wizard page 3:
Configure actions for your data type. These are the options you will have on the report page for data of this type. The default actions are usually sufficient. For more information on actions, see this.

Your Data Type is now setup! You will need to logout/login to see the new data type in your browse options.

SAMPLE: Users of the ext.xsd sample will need to allow access to the three data types in the schema (ext:atlasScalingFactorData, ext:clinicalAssessmentData & ext:segmentationFastData) according to the above instructions. Next, you will need to set the permissions for these types on the USER edit page.

Customizing a listing

The XDAT scripts automatically generate listings for your root level elements. But, these generated listings are often combersome. You can customize the listings to reflect a preferable structure.

The structure of the listings are dictated by xml files which specify what fields will make of the displayed listing for each Data Type. These xml files are located in a sub-directory (display) of the schemas folder next to the relevant schema.

There are many specifications which can be made in display.xml files. The two primary features of the display.xml files are the DisplayFields and the DisplayVersions. The DisplayFields define the fields which can be displayed in a listing. The DisplayVersions specify which fields will be visible in specific listing. The most important DisplayVersion is the one labeled 'listing'. This is the DisplayVersion which will determine what columns appear in the default listing on the website (from the Browse section). The DisplayVersion 'listing_csv' is the version of the listing which will be downloaded by the spreadsheet link.

Open the display document for the Data Type you specified in the previous step.
The display document can be found in the XNAT_HOME/projects/PROJECT/src/schemas/SCHEMA_DIR/display directory.
Remove any un-necessary DisplayFieldRefs from the DisplayVersion 'listing' and save the file.
At the XNAT_HOME directory's command prompt, run the update script located in the bin directory (i.e. bin/update.sh or bin\update.bat). This will process the changes which you made, update the deployments directory, and create an update WAR file (or deploy it directly). Deploy the webapp, by placing the new WAR file directly into the webapp of Tomcat (if it wasn't deployed by the script).
In the Administration section of the website, click the 'More..' section. Click the 'Refresh Display Documents' link. This will reload the display documents, including the file you changed. (If your webapp was not running before the change was made, then this step will not be necessary as the changes will be loaded when the webapp starts up.

Your updated listing should now be visible in the web application.

For more information on how the display documents work, and how you can make more complicated customizations, consult the Listing documentation.

Customizing a report

The XDAT website makes use of Jakarta Turbines structure to allow for the easy creation of secured report Screens. Each report has two primary components; a java class and a Velocity page (.vm). For any report you create, you will need to create both of these components. More info on how it works...

The XDAT scripts automatically generate report pages for your root level elements. These pages are located in the XNAT_HOME/projects/PROJECT/src/base-templates directory.

Edit the report for the Data Type in the previous steps.
Locate the generated Report VM file for that Data Type. It will be titled 'XDATScreen_report_' + Data Type name + '.vm' and be located in the XNAT_HOME/projects/PROJECT/src/base-templates directory.

Copy the generated report VM into the customization directory (XNAT_HOME/projects/PROJECT/src/templates) with the same file name. This is the location where all customized templates should be placed.

Edit the file. Remove any fields which you don't want visible. Restructure the page to present the data in a more personlized format. Save the file.
At the XNAT_HOME directory's command prompt, run the update script located in the bin directory (i.e. bin/update.sh or bin\update.bat). This will process the changes which you made, update the deployments directory, and create an update WAR file (or deploy it directly). Deploy the webapp, by placing the new WAR file directly into the webapp of Tomcat (if it wasn't deployed by the script).

VM files are loaded at each request. So, the website does not need to be restarted to reflect your changes.
For more information and options for customizing reports review the Report documentation.