Modal forms

📘

Getting started

To get started, see modal forms in the app components guide.

Schemas

FormMetadata

Contains the metadata that describes how to display and manage a form.

PropertyTypeDescription
metadata (required)objectThe metadata (i.e., underlying definition) of a form. metadata must exist alongside a template, and its schema must be specific to the value of that template.
» fields (required)arrayAn array of form field objects that are rendered in the order they are in the array. Limit of 30 fields.

Valid object schemas:

- FormField-Checkbox
- FormField-Date
- FormField-Datetime
- FormField-Dropdown
- FormField-MultiLineText
- FormField-RadioButton
- FormField-RichText
- FormField-SingleLineText
- FormField-StaticText
- FormField-Typeahead
» on_change_callbackstringThe URL to POST the form to whenever watched field values are changed.
» on_submit_callbackstringThe URL to POST the form to when the user clicks the submit button. If this is field is omitted then the submission button will be disabled. This is useful if the user must enter information in a watched field first, such as to show additional fields.
» submit_button_textstringThe text to display on the form’s submit button. If not provided, the default text “Submit” will be displayed on the button.
» title (required)stringThe title of the form, which is displayed at the top of the creation form.
template (required)stringThe interface name and version of a distinct form UI layout. A template is directly associated with a particular metadata schema.
{
  "metadata": {
    "fields": [],
    "on_change_callback": "https://www.example.com/on_change",
    "on_submit_callback": "https://www.example.com/on_submit",
    "submit_button_text": "Create New Issue",
    "title": "Create New Issue"
  },
  "template": "form_metadata_v0"
}

FormField-Checkbox

A modal form field that accepts checkbox input. Limit 10 options.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
options (required)[object]An array (minimum length: 1) of CheckboxOption objects.
» id (required)stringThe ID of the option
» label (required)stringThe label of the option. Limit 80 characters.
type (required)stringThe type of modal form field.
value[string]Optional. The values for the form field, which are the IDs of the chosen CheckboxOption objects.
{
  "error": "Please review and change your input",
  "id": "checkbox_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "options": [
    {
      "id": "opt-in",
      "label": "Opt in"
    }
  ],
  "type": "checkbox",
  "value": [
    "opt-in"
  ]
}

FormField-Date

A modal form field that accepts date input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
placeholderstringThe placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
type (required)stringThe type of modal form field.
valuestring(date)¦nullThe value of the field. This takes a date with format YYYY-MM-DD or ISO 8601 date string in UTC.
{
  "error": "Please review and change your input",
  "id": "date_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Date",
  "placeholder": "2022-02-01",
  "type": "date",
  "value": "2022-02-01"
}

FormField-Datetime

A modal form field that accepts datetime input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
placeholderstringThe placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
type (required)stringThe type of modal form field.
valuestring(date-time)¦nullThe value of the field. This value takes the form of an ISO 8601 date string in UTC.
{
  "error": "Please review and change your input",
  "id": "datetime_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Datetime",
  "placeholder": "2022-02-01T14:48:00.000Z",
  "type": "datetime",
  "value": "2022-02-01T14:48:00.000Z"
}

FormField-Dropdown

A modal form field that accepts input via a dropdown list. Limit 50 options.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the *on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
options (required)[object]An array (minimum length: 1) of DropdownOption objects.
» icon_urlstringOptional. The URL for the icon beside the label. If not present, no icon will be displayed.
» id (required)stringThe ID of the option.
» label (required)stringThe label of the option. Limit 80 characters.
typestringThe type of modal form field.
valuestringOptional. The value for the form field, which is the ID of the chosen DropdownOption object.
widthstringOptional. The width of the form field. If not provided, the default value will be "full".
{
  "error": "Please review and change your input",
  "id": "dropdown_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "options": [
    {
      "icon_url": "https://example.com/red.png",
      "id": "red",
      "label": "Red"
    }
  ],
  "type": "dropdown",
  "value": "dropdown_option_1",
  "width": "full"
}

FormField-MultiLineText

A modal form field that accepts multi-line text input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
placeholderstringThe placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
type (required)stringThe type of modal form field.
valuestringThe value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 3000 characters.
{
  "error": "Please review and change your input",
  "id": "multi_line_text_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "placeholder": "Enter the full title of the resource here",
  "type": "multi_line_text",
  "value": "Annual Kick-Off Meeting"
}

FormField-RadioButton

A modal form field that accepts radio button input. Limit 5 options.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
options (required)[object]An array (minimum length: 1) of RadioOption objects.
» id (required)stringThe ID of the option.
» label (required)stringThe label of the option. Limit 80 characters.
» sub_labelstringOptional. The label to display as subtext for the label.
type (required)stringThe type of modal form field.
valuestringOptional. The value for the form field, which is the ID of the chosen RadioOption object.
{
  "error": "Please review and change your input",
  "id": "radio_button_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "options": [
    {
      "id": "radio_option_1",
      "label": "Radio Option 1",
      "sub_label": "#0000FF"
    }
  ],
  "type": "radio_button",
  "value": "radio_option_1"
}

FormField-RichText

A modal form field that accepts rich text input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
placeholderstringThe placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
typestringThe type of modal form field.
valuestringThe value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 3000 characters.
{
  "error": "Please review and change your input",
  "id": "rich_text_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "placeholder": "Enter the full title of the resource here",
  "type": "rich_text",
  "value": "Annual Kick-Off Meeting"
}

FormField-SingleLineText

A modal form field that accepts single-line text input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
placeholderstringThe placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
type (required)stringThe type of modal form field.
valuestringThe value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 200 characters.
widthstringOptional. The width of the form field. If not provided, the default value will be "full".
{
  "error": "Please review and change your input",
  "id": "single_line_text_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Resource name",
  "placeholder": "Enter the full title of the resource here",
  "type": "single_line_text",
  "value": "Annual Kick-Off Meeting",
  "width": "full"
}

FormField-StaticText

A modal form "field" that displays static text. Fields of this type do not collect user input.

PropertyTypeDescription
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
name (required)stringThe text (i.e., label) for the field. Limit 50 characters.
type (required)stringThe type of modal form field.
stylestringOptional. The style of the field. Values can be "default"or "header"If not provided, the default value will be "default".
{
  "id": "static_text_field_1",
  "name": "Please enter the following details:",
  "type": "static_text",
  "style": "default"
}

FormField-Typeahead

A modal form field that accepts typeahead input.

PropertyTypeDescription
errorstringOptional. The developer-specified error message displayed to the user if there is an error with the chosen value.
id (required)stringThe ID of the field, which is used to reference the field. These should be unique across the entire form.
is_requiredbooleanOptional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false.
is_watchedbooleanOptional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false.
namestringThe text (i.e., label) to show in the title of the field. Limit 50 characters.
type (required)stringThe type of modal form field.
typeahead_url (required)stringThe URL that Asana uses to request typehead results from the application server.
valueobjectOptional. The value for the form field, which is the chosen TypeaheadItem object.
» icon_urlstringThe URL of the icon to display next to the title.
» subtitlestringThe subtitle of the typeahead item.
» title (required)stringThe title of the typeahead item.
» value (required)stringThe value of the typeahead item.
widthstringOptional. The width of the form field. If not provided, the default value will be "full".
{
  "error": "Please review and change your input",
  "id": "typeahead_field_1",
  "is_required": true,
  "is_watched": true,
  "name": "Statuses",
  "type": "typeahead",
  "typeahead_url": "https://www.app-server.com/app/typeahead",
  "value": {
    "icon_url": "https://example-icon.png",
    "subtitle": "OTP",
    "title": "OTP Team PF",
    "value": "OTP"
  },
  "width": "full"
}

TypeaheadList

The response to a successful typeahead request.

PropertyTypeDescription
headerstringOptional. Header text to display above the list of typeahead results. If no header is passed in or the value is an empty string, only the typeahead results with be rendered.
items (required)[object]Array of TypeaheadItem objects that indicate typeahead results.
» icon_urlstringThe URL of the icon to display next to the title.
» subtitlestringThe subtitle of the typeahead item.
» title (required)stringThe title of the typeahead item.
» value (required)stringThe value of the typeahead item.
{
  "header": "List of messages",
  "items": [
    {
      "icon_url": "https://example-icon.png",
      "subtitle": "OTP",
      "title": "OTP Team PF",
      "value": "OTP"
    }
  ]
}

AttachedResource

The response to a successful lookup request.

PropertyTypeDescription
errorstringThe error that should be displayed to the user
resource_name (required)stringThe name of the attached resource
resource_url (required)stringThe URL of the attached resource
{
  "error": "No resource matched that input",
  "resource_name": "Build the Thing",
  "resource_url": "https://example.atlassian.net/browse/CP-1"
}

Error schemas

BadRequest

An error response object indicating a bad request (i.e., a status code of 400).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Illegal or malformed request."
  }
}

Forbidden

An error response object indicating a forbidden request (i.e., a status code of 403).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Access forbidden."
  }
}

InternalServerError

An error response object indicating a request that could not be found (i.e., a status code of 500).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Internal server error."
  }
}

NotFound

An error response object indicating a request that could not be found (i.e., a status code of 404).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Not found."
  }
}

Unauthorized

An error response object indicating a unauthorized request (i.e., a status code of 401).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Authorization required."
  }
}