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.

Property	Type	Description
`metadata` (required)	object	The 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)	array	An 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_callback`	string	The URL to `POST` the form to whenever watched field values are changed.
» `on_submit_callback`	string	The 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_text`	string	The text to display on the form’s submit button. If not provided, the default text “Submit” will be displayed on the button.
» `title` (required)	string	The title of the form, which is displayed at the top of the creation form.
`template` (required)	string	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id (required)`	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The 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)	string	The ID of the option
» `label` (required)	string	The label of the option. Limit 80 characters.
`type` (required)	string	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`placeholder`	string	The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
`type` (required)	string	The type of modal form field.
`value`	string(date)¦null	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`placeholder`	string	The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
`type` (required)	string	The type of modal form field.
`value`	string(date-time)¦null	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The 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_url`	string	Optional. The URL for the icon beside the label. If not present, no icon will be displayed.
» `id` (required)	string	The ID of the option.
» `label` (required)	string	The label of the option. Limit 80 characters.
`type`	string	The type of modal form field.
`value`	string	Optional. The value for the form field, which is the ID of the chosen DropdownOption object.
`width`	string	Optional. 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`placeholder`	string	The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
`type` (required)	string	The type of modal form field.
`value`	string	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The 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)	string	The ID of the option.
» `label` (required)	string	The label of the option. Limit 80 characters.
» `sub_label`	string	Optional. The label to display as subtext for the `label`.
`type` (required)	string	The type of modal form field.
`value`	string	Optional. 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`placeholder`	string	The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
`type`	string	The type of modal form field.
`value`	string	The 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`placeholder`	string	The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder.
`type` (required)	string	The type of modal form field.
`value`	string	The 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.
`width`	string	Optional. 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.

Property	Type	Description
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`name` (required)	string	The text (i.e., label) for the field. Limit 50 characters.
`type` (required)	string	The type of modal form field.
style	string	Optional. 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.

Property	Type	Description
`error`	string	Optional. The developer-specified error message displayed to the user if there is an error with the chosen value.
`id` (required)	string	The ID of the field, which is used to reference the field. These should be unique across the entire form.
`is_required`	boolean	Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed `false`.
`is_watched`	boolean	Optional. 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`.
`name`	string	The text (i.e., label) to show in the title of the field. Limit 50 characters.
`type` (required)	string	The type of modal form field.
`typeahead_url` (required)	string	The URL that Asana uses to request typehead results from the application server.
`value`	object	Optional. The value for the form field, which is the chosen TypeaheadItem object.
» `icon_url`	string	The URL of the icon to display next to the title.
» `subtitle`	string	The subtitle of the typeahead item.
» `title` (required)	string	The title of the typeahead item.
» `value` (required)	string	The value of the typeahead item.
`width`	string	Optional. 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.

Property	Type	Description
`header`	string	Optional. 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_url`	string	The URL of the icon to display next to the title.
» `subtitle`	string	The subtitle of the typeahead item.
» `title` (required)	string	The title of the typeahead item.
» `value` (required)	string	The 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.

Property	Type	Description
`error`	string	The error that should be displayed to the user
`resource_name` (required)	string	The name of the attached resource
`resource_url` (required)	string	The 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).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The 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).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The 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).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The 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).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Not found."
  }
}

Unauthorized

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

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Authorization required."
  }
}

📘Getting started

Schemas

FormMetadata

FormField-Checkbox

FormField-Date

FormField-Datetime

FormField-Dropdown

FormField-MultiLineText

FormField-RadioButton

FormField-RichText

FormField-SingleLineText

FormField-StaticText

FormField-Typeahead

TypeaheadList

AttachedResource

Error schemas

BadRequest

Forbidden

InternalServerError

NotFound

Unauthorized

📘
Getting started