# Customizing Data Types

Quick Index

Related Pages

Tutorial Video (from 2010 XNAT Workshop)

This page describes how to create a custom data type to support your particular research requirements. This includes:

• Defining your new data type, including custom attributes
• Creating user interface elements and custom code
• Creating REST API functions
• Packaging your data type for distribution
• Installing the data type into your XNAT deployment

# Defining Custom Data Types

The XNAT application is built around the core xnat.xsd XML schema. 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, image sessions, and session assessors. You can extend the data types defined in the XNAT schema to create your 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 sample schema named ext.xsd. This extends the XNAT schema (see sidebar). You can use this sample to try out the instructions in this tutorial. ext.xsd includes data types that extend the subjectAssessor and mrAssessor abstract types in defined in the core XNAT schema.

Once you have created a new data type, you need to add your data type to your XNAT installation. 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 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)

1. 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.

2. 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.

3. 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.

4. 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 (http:_localhost.8080-xnat)).