XNAT Docs Index

Related Pages

 Click here to expand...
Child pages
  • Sharing Stored Searches

This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation

Skip to end of metadata
Go to start of metadata

Quick Index

About Bundles

Stored Searches, also referred to as bundles, 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.

A bundle has several key variables:

ID

This is the primary identifier of a bundle. It must be unique to this bundle.

Description

This brief description is the text which will be used to identify this bundle.

Pivot Data Type (Root Element)

Every bundle must have a pivot data type, which is the root data set of the of the bundle. It is used to join data types together. All other data types in the bundle will be joined to this data type (rather than to each other). XDAT builds a bundle by starting with the root data type, joining other data types to the root data type, processing the WHERE clause to limit the rows in the result set, and outputting the result set according to the specified displayed fields.

Sort By Data Type & Field

These two variables combine to identify the field which should be used to sort the rows in the bundle.

Display Fields

The display fields of a bundle identify which columns are displayed in the bundle. These fields reference <DisplayField> elements from the display documents (used in the listings). The element_name and field_ID variables are used to specify which previously defined <DisplayField> elements should be included in the bundle. The sequence is specifies the order that the fields (columns) should appear in the bundle. The type is the resultant type of the data fields. The header is the text that appears as the column header.

WHERE Clauses

WHERE clauses are used to limit the rows which are included in the bundle. Without any WHERE clauses, all of the rows for the pivot data type would be included in the bundle. The web interface allows the creation of simple WHERE Clauses.

Multi-level WHERE Clauses

For more complicated (multi-leveled) clauses, XML may be needed to define the bundle. 

The method variable defines whether the specified WHERE clauses should use 'AND' or 'OR' logic.

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
This allows you to limit the result set by a pre-defined field (which may be derived) or directly from a data value.

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

  • =
  • <
  • <=
  • >
  • >=
  • LIKE (for string types)

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 %

Allowed Users

These are the logins of the users who are allowed to view this bundle.

Creating and Editing A Bundle

Bundles can be created via two methods, XML Storage or Edit Page.

Edit Page

Administrators are allowed to access, create, and edit bundles in the Administration section of the website on the Bundles page.

XML Storage

Bundles can also be stored using the StoreXML task in the same way that your other data is stored. The bundle should be built according to the specifications of the xnat_builder/projects/PROJECT_NAME/src/schemas/security/security.xsd schema. The XML should be stored using the StoreXML task from the command prompt.

  • No labels