Using Custom Forms
What are Custom Forms?
Researchers gathering data in their XNAT often find that they have additional metadata attributes that are not natively supported by the XNAT data model. For example, a clinical trial may want to capture enrollment data such as "Enrollment Date", "Acceptance of Terms", and "Study Status" and append those data directly to a subject record.
XNAT has supported the ability for project owners to append attributes like these to XNAT datatypes, using Custom Variables. However, there have been several known drawbacks, including: a cumbersome approach to defining custom variable sets, overlapping editing permissions for shared variable sets, very basic end user experience, and a complete lack of API support, which makes standardization difficult.
Custom Forms offers a modernized approach, importing and extending the Form.io library to be fully integrated with XNAT, its data model, and the XNAT search engine.
The initial MVP release of Custom Forms, included in XNAT 1.8.8, can sit alongside legacy Custom Variables. However, we intend to fully deprecate Custom Variables and provide an easy migration path from Custom Variable sets to Custom Forms in a future release. We highly encourage feedback from the community of XNAT users and administrators in the XNAT Discussion Group.
Form administrators are presented with an intuitive, drag-and-drop interface that allows them to place standard form elements or build complex layouts with custom validations and behaviors.
Form elements are highly customizable, and offer the ability to enforce custom validation, or trigger custom script executions.
Form definitions are saved as JSON objects, which can be standardized across multiple XNAT instances.
Because there is powerful scripting capability that comes with Form.io, the ability to create and manage custom form definitions is restricted to site administrators and a newly created Form Administrator user role. For this reason, we have not fully deprecated Custom Variables yet. See Custom Forms Administration.
Defining a Custom Form and Integrating it into an XNAT Edit Page
The first step in defining a custom form is knowing what part of the XNAT data model to attach it to. You can add custom attributes to any of the following in the XNAT data hierarchy:
- Projects
- Project Assets (experiments that are not tied to a subject)
- Subjects
- Nonimaging Subject Assessors (such as clinical assessments)
- Image Sessions (MR, CT, etc)
- Image Assessors (such as a Rad Read or Manual QC)
You cannot currently add Custom Forms to image scans in XNAT
Once you have chosen a datatype to extend, the process of defining a custom form is as easy as dragging and dropping the elements of your choice into the order and layout of your choice, and then customizing their presentation and behavior as you see fit. Once a form has been created and enabled in a project, XNAT's default edit screens will automatically display the custom form fields.
If you are working with a custom developed XNAT datatype that has a customized edit screen, that edit screen code may need updating to ensure that custom forms are supported. See Integrating Custom Fields display in Report and Edit Pages of custom datatype.
Example: Custom Forms embedded within a Subject Edit page.
Displaying Custom Form Data in an XNAT Report Page
Once custom form data has been saved by a user, it appears automatically in the default XNAT report page for that data item. Multiple forms can be attached to a given data element, and each form appears in its own tab.
If you are working with a custom developed XNAT datatype that has a customized report page, that report page code may need updating to ensure that custom forms are supported. See Integrating Custom Fields display in Report and Edit Pages of custom datatype.
Searching on Custom Form Data
Custom Form data is stored in XML alongside all other data attributes for a given element (see below), and XNAT has exposed this data as first-class searchable fields. Custom form fields can be added to a given search table by using the "Edit Columns" feature.
See: Custom Form Integration with XNAT Search
How is Custom Form Data Stored in XNAT?
Custom Forms data is stored in XML using the "Custom Fields" attribute that was already built into the XNAT data model and integrated with the XNAT search engine. Form data for all forms on a given data element is stored in a JSON object, with each form's unique identifier (UUID) used as a key associated with that form's inputs and values.
APIs have been built into XNAT that allow for scripted interaction with these custom fields and their form data. See Custom Form API
Using Custom Forms in More Than One Project
Like Custom Variable sets, Custom Forms can be set to be specific to a project, or set to "site-wide", which means they will apply to every project in the site including those that have not been created yet. However, Custom Forms has more refined capabilities for managing these subscriptions, including allowing project owners to opt out of a site-wide form, and enabling Form Administrators to manage which projects are subscribed to various forms.
See: Opting in or Out of a Custom Form in your Project
See: Managing Project Subscriptions to Custom Forms
Data Sharing with Custom Forms
Sharing data that has attributes from Custom Forms to other projects can be complicated, depending on whether or not those projects also have Custom Forms enabled. For full documentation of intended behavior, see: Data Sharing with Custom Forms