Managing Data Types in XNAT

The Data Type management Admin UI will be updated in a future release of XNAT. These documents will be updated accordingly.

XNAT loads in a variety of XML Schema (XSD) which contain many interesting data structures. Not all of these data structures will be used in all XNAT instances (in fact most XNATs will likely only use a small number of them such as xnat:projectData, xnat:subjectData, xnat:mrSessionData, etc). Because of this, and to keep data type administration more manageable, only the most popular data types are setup by default in XNAT. There are other data types that are included in XNAT that will be of interest to fewer XNAT sites. These data types should be added through the user interface before they can be used.

If your desired data type is not included in XNAT, you can create your own data type schema and then add that data type to XNAT. See: XNAT Data Type Development

Administering Data Types

Data Types are managed from within the Administration section -> Data Types. The below screenshot shows all the data types that come pre-setup in XNAT.

Manually Adding A New Data Type

If you have added a new data type as an XNAT plugin, it should be automatically enabled. If it is not and you are having to enable it manually, the plugin developer should double-check the plugin class annotations. See XNAT Data Type Development: Configuring Data Types in Plugin Configurations.

If there is a data type you want to use that is not included in the above list, you can click the 'Setup Additional Data Types' button. This will open a modal containing a dropdown from which you can select the Data Type you want to add. The dropdown list will display all root-level elements (elements which can validly be the root of a new xml document) which are contained in your loaded schema but not yet registered in your database. If your desired data type is not included in this list either, you can either write your own data type schema, or try to find an existing one in the XNAT Marketplace.

Once you have selected the data type you wish to add from the 'Setup Additional Data Types' modal and clicked Submit, the modal will show some access options for you to configure for your data type. On this form you can specify whether or not the data type should be secured, searchable, etc. For the most part, the default selected values should be appropriate. You should make sure these setting are what you want and add relevant singular and plural names. Tip: Keeping these names short will make your user interface less cluttered. 

You will typically want your data types to be secured. When a user account attempts to query/retrieve data for a secured data type, XNAT will review the Primary Security Fields, xdat:user and xdat:userGroups to determine if they have access to see that data. The user and userGroup elements will store a list of the values for those corresponding security fields for which the user or group should have permissions. So, if the primary security field is xnat:mrSessionData/project and user X has access to xnat:mrSessionData where xnat:mrSessionData/project is equal to TEST1, then the database will limit queries to data which matches that.

The final screen of the wizard (image below) allows you to customize the actions for your new data type. Once again, the defaults should be appropriate most of the time.

Once these screens have been complete, your new data type will be accessible through the web interface.

Edit Existing Data Type

There are two ways to edit an existing data type through the UI. Some settings can be changed from the main data types page, while others require you to edit the data type in a modal.

In the example below, after going through setup for the screening assessment data type, I realized that I had forgotten to assign singular and plural names for the data type. After I finish entering the new singular and plural names for that data type, I will click 'Save' for my changes to take effect. Changes to the values in any of the columns in the table can be made in this way.

However, not all of the data type settings you configured when setting up the data type are editable in this way (otherwise the table would become unmanageably large). To change these settings, simply click the link in the Element column for the data type you wish to edit and then click Edit from the Actions menu in the modal that comes up. The modal shows all the same options that show up when setting up additional data types. After making whatever changes you want to make, don't forget to click the submit button at the bottom of the modal for these changes to take effect.

You will need to use the modal's scrollbars in order to see the Submit button, as well as some of the content you can edit.

Delete Existing Data Type

To delete an existing data type, simply click the link in the Element column for the data type you wish to delete and then click Delete from the Actions menu in the modal that comes up. 

You should not delete a data type definition if you have data of that type in your XNAT. This could cause your XNAT to behave strangely.