Getting startedTo get started, see rule actions in the app components guide.
Schemas
RanAction
The response to an action request.
Property | Type | Description |
---|---|---|
action_result (required) | string | Specifies any additional information that the app wants to send to Asana on completion of the action. Can only be resources_created or ok . |
error | string | The error that should be displayed to the user. |
resources_created | [object] | A field with the data corresponding to the action_result value. Each action_result has its own data field shape that Asana expects. resources_created expects the name and URL of the resources that the action created. |
» 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. |
{
"action_result": "ok",
"error": "That resource no longer exists",
"resources_created": [
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
]
}
FormMetadata
Contains the metadata that describes how to display and manage a form.
Property | Type | Description |
---|---|---|
| object | The metadata (i.e., underlying definition) of a form. |
» | 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: |
» | string | The URL to |
» | string | The URL to |
» | string | The text to display on the form’s submit button. If not provided, the default text “Submit” will be displayed on the button. |
» | string | The title of the form, which is displayed at the top of the creation form. |
| string | The interface name and version of a distinct form UI layout. A |
{
"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 | The ID of the field, which is used to reference the field. These should be unique across the entire form. |
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 | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . |
is_required | 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 . |
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 . |
is_watched | 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."
}
}