icon-administration.png
Administering XNAT

Monitoring XNAT


Advanced Topics

[Edit Nav]


Managing XNAT Data Types

Introduction

XNAT loads in a variety of XML Schema (XSD) which contain hundreds of interesting data structures. From these data structures, XNAT attempts to generate a usable web interface which allows you to store, retrieve, navigate and query data which corresponds to those structures. If the web interface showed all of the available types of data from the schema in the interface, it would quickly become unusable. For this purpose, XNAT allows you to register certain types of data (data-types) as being of particular interest to the users of the site.

By default, XNAT has certain data-types preregistered (xnat:projectData, xnat:subjectData, xnat:mrSessionData, etc). These types have been preconfigured by the XNAT team to make them usable by a wide variety of users. You can modify the configuration of these preregistered data types or add new ones. Modifying these data types can easily allow you to customize the navigation and look of your site.

Data Types are managed from within the Administration section -> Data Types.
xnat_admin_dataType_list.png
Click on an element name to see a detailed report for that data type.

Security

XNAT security relies on the registration of the relevant data types. Only data for registered data types can be secured. Thus, xnat:mrSessionData data can be secured, xnat:imageScanData data can not.

In order to secure a data type, you can add Primary Security Fields to the data type and check Is Secure TRUE. There is a correlating structure within the xdat:user type and xdat:userGroup type which is built to hold permissions based on your defined Primary Security Fields.

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.

If you extend the xnat:subjectAssessorData or xnat:imageAssessorData types, then much of the security infrastructure will be provided for you. They default to being managed by the project field. To secure these data types, you need only mark Is Secure TRUE. Then your data should be properly secured automatically. If you build your own xml structures which do not extend our usual types, then you will need to manage the permissions accordingly.

Labeling

I say tomato, you say tomata. If you would like to customize how the data types in your site are labeled, you can using the Singular and Plural Names in the Data Type management interface.

Data Type Actions

Via the Data Type management interface, you can control which actions are available when users are interacting with the actual data.

Report Actions

The actions box displayed on data reports is customizable based on the data type.
xnat_admin_report_action_list.png

You can add and remove links from the action box via the data type management interface.
xnat_admin_report_actions.png
Name
REQUIRED
The name of the action. This should correspond directly to java/velocity screen which extends the SecureReport class.
Display Name
REQUIRED
The text to be displayed as a link.
Grouping
OPTIONAL
Value used to group requests in the Actions listing. Using this attribute will cause the link to be in a sub-menu.
Image
OPTIONAL
Icon to use as part of the link. The image file should be located in the images folder in the installation.
Popup
OPTIONAL
sometimes, never (DEFAULT), always. Whether the link should open in a popup window.
Secure Access
OPTIONAL
read (DEFAULT), edit, delete, create. If you need access to this link to be limited to users with certain permissions choose the appropriate level. If you choose edit, then only users with permission to edit the relevant data will see that link.
Additional Parameters
OPTIONAL
Additional parameters to be passed to the screen.
Sequence
OPTIONAL
Order in which links should appear.

Listing Actions

These are the actions which are available when viewing data of this type in the listing format.
xnat_admin_listing_actions.png
Name
REQUIRED
The name of the action. This should correspond directly to java/velocity screen which extends the org.nrg.xdat.turbine.modules.actions.ListingAction class.
Display Name
REQUIRED
The text to be displayed as a link.
Image
OPTIONAL
Icon to use as part of the link. The image file should be located in the images folder in the installation.
Popup
OPTIONAL
sometimes, never (DEFAULT), always. Whether the link should open in a popup window.
Secure Access
OPTIONAL
read (DEFAULT), edit, delete, create. If you need access to this link to be limited to users with certain permissions choose the appropriate level. If you choose edit, then only users with permission to edit the relevant data will see that link.
Additional Parameters
OPTIONAL
Additional parameters to be passed to the screen.
Sequence
OPTIONAL
Order in which links should appear.

Adding Data Types

XNAT has an integrated Wizard for registering new data types. You can access the wizard via the Setup Additional Data Type link on the Data Types listing page.
xnat_admin_add_dataType1.png
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. The list is limited to these elements to prevent the inclusion of hundreds of fields. If you want to register a data type, you should make sure it is capable of being a root level document.

After selecting your data type from a list, you will be able to specify a few of the details concerning your data type.
xnat_admin_add_dataType2.png
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 and add relevant singular and plural names. Tip: Keeping these names short will make your user interface less cluttered.

xnat_admin_add_dataType3.png
The final screen of the wizard 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.

Modifying Data Types

xnat_admin_edit_dataType.png
Existing data types can be modified by clicking on the Edit link on the Data Type report. Using this form you can modify the security, labels, and actions associated with your data types.

xnat_admin_edit_dataType2.png