Importing and Exporting Custom Form Definitions

A custom form definition, also known as, form schema, is stored in XNAT as a JSON. Importing and exporting a custom form definition involves handling the JSON representing the form schema. 

Note that at this point, the following advanced tracking features for custom form importing are not supported:

• Form versioning

• Form authoring

• Restricting editing on an imported form

• Saving to or importing from a form repository

Importing a form definition

There are two ways to import a form definition, viz. using the XNAT Form Builder or the Custom Form API.

Import using  XNAT Form Builder

• Login as a user who can create custom forms
• Create a form with just one component, say a Text Field and save the form
• Go back to edit the newly created form and click on Edit JSON
• Copy the JSON of the form you want to import into the form JSON editor and click save. 
• Note:
  • Copying the JSON as is, will also set the form title to be the same as the one at the source. 

 Import using Custom Form API

While importing a form definition using the API, you will have to make sure that:

• the datatype that the form applies to, is configured on your XNAT instance
• the form schema JSON is a valid form definition. XNAT will not validate the JSON against the form.io form schema rules
• if the form you are importing is a project specific form, the project id(s) exist on your XNAT instance.

Using the API to import a form definition involves providing the meta-data about the form, that is, 

• the display order of the form
• whether the form is applicable across the site or applies to specific projects
• if the form is a specific to a project(s), what are the project ids

A PUT to the endpoint xapi/customforms/save will save the form definition. A response of 201 implies that the form has been saved successfully and the API returns the form UUID assigned to the form.

curl -u XNAT_USER_NAME:PASSWORD -X PUT "YOUR_XNAT_URL_HERE/xapi/customforms/save" -H "Content-Type: application/json;charset=UTF-8" -d FORM_JSON_WITH_METADATA_HERE

The following json with form metadata, is a form that applies to the Subject datatype (lines 6-9), is not a site wide  form (line 10) and applies to the project proj2 (lines 11-16).  Line 19 onwards is the form schema.

{
  "submission": {
    "data": {
      "zIndex": 10,
      "xnatDatatype": {
        "label": "Subject",
        "value": "xnat:subjectData"
      },
      "isThisASiteWideConfiguration": "no",
      "xnatProject": [
        {
          "label": "proj2",
          "value": "proj2"
        }
      ]
    }
  },
  "builder": {
    "display": "form",
    "title": "Imported Form",
    "settings": {},
    "components": [
      {
        "label": "Text Field 01",
        "key": "textField01",
        "type": "textfield",
        "input": true,
        "tableView": true
      }
    ]
  }
}

A curl call to save the above json would look like:

curl -u XNAT_USER_NAME:PASSWORD -X PUT "YOUR_XNAT_URL_HERE/xapi/customforms/save" -H "Content-Type: application/json;charset=UTF-8" -d "{\"submission\":{\"data\":{\"zIndex\":10,\"xnatDatatype\":{\"label\":\"Subject\",\"value\":\"xnat:subjectData\"},\"isThisASiteWideConfiguration\":\"no\",\"xnatProject\":[{\"label\":\"proj2\",\"value\":\"proj2\"}]}},\"builder\":{\"display\":\"form\",\"title\":\"Imported Form\",\"settings\":{},\"components\":[{\"label\":\"Text Field 01\",\"key\":\"textField01\",\"type\":\"textfield\",\"input\":true,\"tableView\":true}]}}"

Exporting a form definition

Like importing a form definition, exporting a form definition can be done using the XNAT Form Builder  or the Custom Form API. However, using the Custom Form API is a more involved process and we would not recommend to the use the API to export the form.

Export using the XNAT Form Builder

• Login as a user who can create forms
• From the form dashboard, click on the form you want to export
• Click on Edit JSON and copy the form schema JSON
• Save the copied JSON in a file. 
• You can share this file with others to import the form into their XNAT instance.