Share Custom Data Tables as Stored Searches for Project Reporting

Developer Note

This documentation focuses on the creation and propagation of custom data tables by XNAT Administrators. If you are interested in creating a custom report page in support of a new data type, see XNAT Developer Documentation.

Any ongoing study will have regular needs to report on their subjects and their data gathering. XNAT allows you to generate custom data tables, then share them among a selected set of users (or site-wide) to meet this need. 

Generate and Save a Stored Search

The UI for managing site-wide stored searches, or "bundles", will be updated in a future release of XNAT. As such, this documentation will be updated.

Any user can generate a new data table based on one or more XNAT data types, by using the Advanced Search or by customizing an existing data table. Once a new search has been created, the user can save it as a stored search and it will appear in their list of stored searches in the top navigation. 

The user's view of their own stored searches in the top navigation

Sharing a Stored Search – or Bundle – with Other Users

Stored Searches are also referred to as bundles in the XNAT Admininstration UI. These are searches that other users are allowed to view. They are a useful tool for organizing subsets of data into easily viewed combinations. The definition of each bundle is stored in the database in the same manner as your data. The bundles are loaded into the application server's context when they are first requested. Each bundle has a list of users who are allowed to view it. These users will have a link to the bundle in their navigation menu.

You can administer bundles at Administer > Bundles. You can also upload complex bundle definitions via REST API (see below).

A bundle has several key variables:

Building WHERE Clauses to Filter Your Bundle's Results

Users can manipulate data table filters in the XNAT UI to create simple WHERE clauses in their stored searches. However, there are limitations on what these filters are designed to do. For more complicated (e.g. multi-leveled) clauses, you may need to use XML to define the bundle. If this is the case, use the REST API to upload your bundle, as specified below.

An example XML structure of your WHERE clause would look like this:

 <xdat:search_where method="AND">
    <xdat:child_set method="AND">
        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData.DATE</xdat:schema_field>
            <xdat:comparison_type><</xdat:comparison_type>
            <xdat:value>01/01/2017</xdat:value>
        </xdat:criteria>

        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData.DATE</xdat:schema_field>
            <xdat:comparison_type>>=</xdat:comparison_type>
            <xdat:value>01/01/2016</xdat:value>
        </xdat:criteria>
    </xdat:child_set>
</xdat:search_where>

This example WHERE clause would provide a "between" filter that allows you to set boundary values for the MR Session Date field (xnat:mrSessionData.DATE), returning only sessions that were captured in the year 2016.

Note the use of method="AND" for all criteria assigned to the date field. This is an example of a search that cannot be performed in the UI for filtering data tables, since multiple filters on the same column of data will always use "OR" logic for joining results. Why is this important? A filter set to return all MR Sessions (after Jan 1, 2016) OR (before Jan 1, 2017) would return every MR Session in the database.

As of XNAT 1.7, a BETWEEN filter has been added to the data table filtering UI to get around this particular issue.

The display_field or schema_field is the data field which should be used to process the clause. Whether using a display or schema field, the field should start with the root data type of the field:

• If it references a pre-defined display type, then it should reference the display field's ID, i.e. data_type.Field_ID
• If it references a schema field, it should reference the field in the same manner that is used in the display documents, i.e. data_type/schema_field

The comparison_type variable specifies what comparison expression to use in the WHERE clause. It can be one of the following values:

The value variable specifies the value to use in the WHERE clause comparison.

The custom_search and override_value_formatting variables can be used to directly specify an unconventional WHERE clause

• custom_search can include the text of the WHERE clause. This text must be valid SQL as it will be included directly in the SQL WHERE clause
• override_value_format specifies that XDAT should not try to format the expression with characters like ' or %

Upload an XML Stored Search Definition via the UI

It is easy to upload an XML definition of a stored search via the UI. Go to Upload > XML in the top nav to get started. See here for more details: Uploading Data via StoreXML. Once you have uploaded the stored search, you can access it and edit user permissions in the Admin UI by going to Administer > Bundles (Stored Searches).

Uploading a Stored Search Using REST API

Stored Searches can be uploaded using the StoreXML task in the same way that your other data is stored. The XNAT REST API gives you a way to do this programmatically, or from the command line.

See REST API Documentation: Stored Search API

Using the REST API

If you are unfamiliar with using the REST API in XNAT, visit the XNAT REST API Documentation