Custom Forms Administration

As an administrator of your XNAT, you will have significant control over the custom forms which are able to be used in your system. You will have the responsibility of creating, editing, deleting and associating custom forms with projects throughout you XNAT instance. You will also have the ability to provide other users with administration power over custom forms. Within this page, we will outline the specific abilities provided to administrators to help them manage their site's custom forms.

Enabling a Forms Admin User 

Within your XNAT instance, you may wish to allow certain users to create, edit, and delete custom forms. To do this, a user must be given the role of ‘Custom Form Manager’ within the XNAT. Providing a user with this permission gives them broad power over the state of the custom forms within an XNAT instance. Custom Form Managers have access to all of the custom forms within the system and can create, edit, enable, disable,  and delete forms as well as associate those forms with any of the projects within the system. As such, it is important to be cautious with who you allow to take on this role within your XNAT - assigning it to untrusted users could result in significant disruptions to the state of your custom forms and by extension your data.

However, Custom Form Managers do *not* gain control over any of the projects or data within your XNAT outside of custom forms. While they can associate forms with a given project or edit forms which are associated with experiments, for instance, they do not gain access to data as a result of their role as Custom Form Manager.

In order to provide a user with the role of Custom Form Manager, navigate to Administer -> Users within the top navigation bar. Then click on the username of the user to which you wish to provide the role to. Then, in the pop-up menu, click ‘Edit Advanced Settings’ and if you scroll down you should see a checkbox for ‘Custom Form Manager.’ Clicking this and hitting save will associate the user with this role and within the ‘Role’ column of the table you should see ‘CustomFormManager’ for that user.

Viewing Custom Forms in a Site

As an administrator or a user with the Custom Form Manager role enabled, you have access to a listing of all of the custom forms found within your XNAT. In order to access this table, you can navigate to Tools -> Custom Forms -> Manage Custom Forms within the top navigation bar. Doing so will bring you to a table such as this one:

The table will provide you with a listing of all of the forms present within the XNAT as well as the datatype it affects, the project(s) it is associated with, who created the form, and the current status of the form - enabled or disabled. Finally the table will allow an administrator or Custom Form Manager to perform a list of several actions on the form which will be outlined in upcoming sections.

Creating and Editing a Custom Form

Form creation is limited to administrators and users that have been given the Custom Form Manager role outlined above. You may being the process of form creation beginning from that Manage Custom Forms page outlined above. For a full outline of the process of creating a form, you can navigate to Creating a Custom Form.

Additionally, the custom forms table will allow administrators and Custom Form Managers to edit any forms which have been created previously. This action should be undertaken with care, especially in the case that data has already been created within the XNAT and associated with the particular custom form. For a full outline of the process of editing custom forms, see: Editing Custom Forms.

Enabling and Disabling Forms

Within the table printout shown above, a user is able to view the 'Status' column which lists whether each form is currently in an 'Enabled' or 'Disabled' state. Disabling a form can be performed by clicking on the toggle within the 'Status' column and then clicking 'Ok' at the resulting pop-up. Once this action is performed, the form will no longer be in use and when new data is created with that data type, the form will not appear within the creation page. Additionally, any instances of data that have already been created will no longer show the form fields which were associated prior to the form being disabled - both in report pages and in search listings. However, this prior data will be persisted and can be easily made available again by simply re-enabling the form. The method for re-enabling a form is the exact same as disabling it.

Managing Project Subscriptions to Custom Forms

When creating a form, a user will have the option of making the form either site-wide or project specific - this can be referred to as the form's scope. In the former case, the form will be associated by default with all of the projects within the system as well as all projects which are created in the system in the future. In the case of project specific forms, the form will need to be specifically associated with any project that wishes to use the form's functionality. An outline of how to set the scope of the custom form during form creation can be found within Creating a Custom Form.

However, you may wish to change the specifics of the scope of your custom form after it has been created. For instance, as an Admin or Custom Form Manager, you may wish to change the project subscriptions for a given form; this could be a case of wishing to associate new projects with a project specific form, or you may wish to opt certain projects out from a form with a site wide scope. You can also convert project-specific forms to becoming a site-wide default for all projects.  

In either case, you can find a explanation for how this can be performed within: Managing Project Subscriptions to Custom Forms.

Deleting a Custom Form

(Describe delete action. What happens if there is already form data?) 

Deleting of form data can be performed from within the Manage Custom Forms page by clicking on the Trash Can icon within the actions box for a given form. As with the previous actions in this section, this can only be performed by Custom Form Managers as well as Admins of the XNAT site. We encourage you to take extreme care when deleting any forms as it is a non-reversible action.

If a custom form already has data associated with it - that is, if users have already created instances of data utilizing that custom form - the delete icon will be shown as unavailable. Additionally, using the XNAT API to attempt to perform a delete action will return a failure notification. This is done to ensure that no issues are created within the XNAT due to elements pointing to non-existent custom forms. Instead, we encourage you to disable any forms with data that you wish to delete as outlined above. This will ensure that none of the custom forms data collected for the given elements will be shown to users but will ensure persistence of the data.

Exporting or Importing a Custom Form Definition

While editing a custom form as outlined above in 'Creating and Editing Custom Forms,' a user may select the 'Edit JSON' button in order to perform edits on the JSON of the custom form directly rather than utilizing the form editor. This JSON is what is actually persisted by XNAT and used to serve users the custom form outline later in the pipeline. Editing this JSON directly can be a useful way to import or export your custom forms within XNAT to or from other sources. You can find more on this process within: Importing and Exporting Custom Form Definitions.