Managing Data Types

Quick Index

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.


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 to-mah-to. 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.

You can add and remove links from the action box via the data type management interface.

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.

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.


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.


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.


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


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.

$label.name