This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation
For most applications, the standard set of data types provided with XNAT can cover most of your data requirements. But for most applications there is some area of your data requirements where the standard set of data types doesn't cover you. This may be a subject assessor required for your particular clinical or research needs, extra data that needs to be included with resources of a particular imaging modality, or even a new imaging modality specific to your particular set of projects.
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 (see sidebar). 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.
XNAT Schema Extension
A sample schema, ext.xsd, which extends the XNAT schema is available in XNAT_HOME/deployments/PROJECT_NAME/src/schemas/ext folder. This schema has three root elements viz. ClinicalAssessment, AtlasScalingFactor and SegmentationFast. ClinicalAssessment extends xnat:subjectAssessorData and AtlasScalingFactor, SegmentationFast extend xnat:mrAssessorData
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 (
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
XNAT_HOME/projects/xnat/InstanceSettings.xml. To activate it, remove the comment tags (<!-- and -->).
XNAT_HOME/projects/PROJECT/src/java/org/nrg/xdat/omdirectory. 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.
XNAT_HOME/projects/PROJECT/src/base-templatesdirectory. Here you will see the generated velocity templates for your root level data types. These will be used later.
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.
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 (http:_localhost.8080-xnat)).
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.
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. Related: Understanding Data Sharing in XNAT's Security Structure
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. Related: Adding Custom Features and Content.
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.