Custom fields
Premium feature
Custom fields are an Asana Premium feature. Integrations which work with custom fields need to handle an assortment of use cases for free and premium users in context of free and premium organizations. For a detailed examination of which data users will have access in different circumstances, review the section below on access control.
In the Asana application, tasks, projects, and portfolios can hold user-specified custom fields which provide extra information (e.g., a "priority" property with an associated value, or a number representing the time required to complete a task). This lets a user define the type of information that each item within a project or portfolio can contain in addition to the built-in fields that Asana provides.
Characteristics
- There is metadata that defines the custom field. This metadata can be shared across an entire workspace, or be specific to a project or portfolio
- Creating a custom field setting on a project or portfolio means each direct child will have the custom field. This is conceptually akin to adding columns in a database or a spreadsheet: every task (row) in the project (table) can contain information for that field, including "blank" values (i.e.,
nulldata). For portfolio custom fields, every project (row) in the portfolio (table) will contain information for the custom field - Custom field settings only go one child deep. This means that a custom field setting on a portfolio will give each project the custom field, but not each task within those projects
- Tasks have custom field values assigned to them
- Along with other returned metadata, a custom field (regardless of type) will include
display_value, a read-only field that will always be a string. For apps that use custom fields, this is a great way to safely display/export the value of a custom field, regardless of its type. We suggest apps use this field in order to future-proof for changes to custom fields
Types of custom fields
Integrations using custom fields need to be aware of the six basic types that a custom field can adopt. These types are:
text- an arbitrary, relatively short string of textnumber- a number with a defined level of precisionenum- a selection of a single option from a defined list of options (i.e., mutually exclusive selections)multi_enum- a selection of one or more options from a defined list of options (i.e., mutually inclusive selections)date- a reference date with an optional time valuepeople- a list of active contributors (i.e., where their relationship to the work is defined in the custom field title)
NOTE: formula custom field is another type of custom field but the type is number and the is_formula_fieldvalue is true. Custom IDs is another field, identifiable when the id_prefix is a unique string instead of null. Currently, both are read-only.
Example use case
Consider an organization that has defined a custom field for "Priority". This field is of enum type and can have user-defined values of Low, Medium, or High. This is the field metadata, and it is visible within, and shared across, the entire organization.
A project is then created in the organization, called "Bugs", and the "Priority" custom field is associated with that project. This will allow all tasks within the "Bugs" project to have an associated "Priority".
A new task is created within "Bugs". This task, then, has a field named "Priority" which can take on the custom field value of one of [null], Low, Medium, and High.
Custom fields in the API
These custom fields are accessible via the API through a number of endpoints at the top level (e.g., /custom_fields and /custom_field_settings) and through requests on workspaces, portfolios, projects, and tasks resources. The API also provides a way to fetch both the metadata and data which define each particular custom field, so that a client application may render proper UI to display or edit the values.
Text fields are currently limited to 1024 characters. On tasks, their custom field value will have a text_value property to represent this field.
Number fields can have an arbitrary precision associated with them; for example, a precision of 2 would round its value to the second (hundredths) place (e.g., 1.2345 would round to 1.23). On tasks, the custom field value will have a number_value property to represent this field.
Formula fields are currently read-only and is represented by the is_formula_field value being true
Custom ID fields are read-only and have a id_prefix string (instead of null) that is the unique custom ID string for the custom field.
Enum fields
Enum fields represent a selection from a list of options. On the metadata, they will contain all of the options in an array. Each option has 4 properties:
gid- the GID of this enum option. Note that this is the GID of the individual option. The custom field itself has a separategid.name- the name of the option (e.g., "Choice #1")enabled- whether this field is enabled. Disabled fields are not available to choose from when disabled, and are visually hidden in the Asana application, but they remain in the metadata for custom field values which were set to the option before the option was disabled.color- a color associated with this choice.
On the task's custom field value, the enum will have an enum_value property which will be the same as one of the choices from the list defined in the custom field metadata.
Querying for custom fields
For custom fields shared across the workspace or organization, the workspace can be queried for its list of defined custom fields. Like other collection queries, the
fields will be returned as a compact record; slightly different from most other compact records is the fact that the compact record for custom fields includes type as well as gid and name.
Accessing custom field definitions
The custom fields reference describes how the metadata which defines a custom field is accessed. A GET request with a gid can be issued on the /custom_fields endpoint to fetch the full definition of a single custom field given its gid from (for instance) listing all custom fields on a workspace, or getting the gid from a custom field settings object or a task.
Associating custom fields with a project or portfolio
A mapping between a custom field and a project or portfolio is handled with a custom field settings object. This object contains a reference for each of the custom fields and the project or portfolio, as well as additional information about the status of that particular custom field (e.g., is_important, which defines whether or not the custom field will appear in the list/grid on the Asana application).
Accessing custom field values on tasks or projects
The tasks reference has information on how custom fields look on tasks. Custom fields will return as an array on the property custom_fields, and each entry will contain, side-by-side, the compact representation of the custom field metadata and a {typename}_value property that stores the value set for the
custom field.
Of particular note is that the top-level gid of each entry in the custom_fields array is the gid of the custom field metadata, as it is the compact representation of this metadata. This can be used to refer to the full metadata by making a request to the /custom_fields/{custom_fields_id} endpoint as described above.
Custom fields can be set just as in the Asana-defined fields on a task via POST or PUT requests. You can see an example in the update a task endpoint.
Custom fields on projects follow this same pattern.
Adding (or updating) a task's custom field value
As an example, let's say you want to create a task in a particular project, and that project includes two custom fields: a text custom field (i.e., "resource_subtype": "text"), and an enum custom field (i.e., "resource_subtype": "enum").
To create the task with values for these two custom fields, you should first make a request to GET /projects/{project_gid}/custom_field_settings, which returns a (compact) list of all of the custom fields settings on a project. Note the GID values of these custom field settings in your project, as well as the GID values of the individual enum options available.
Once that is done, you can make a request to POST /tasks, providing the GIDs of the custom fields from above, along with your intended values for these custom fields. Here's an example of such a request:
curl --request POST \
--url 'https://app.asana.com/api/1.0/tasks' \
--header 'accept: application/json' \
--header 'authorization: Bearer PERSONAL_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--data '
{
"data": {
"custom_fields": {
"TEXT_CUSTOM_FIELD_GID": "Sample value for a custom field of type text",
"ENUM_CUSTOM_FIELD_GID": "ENUM_OPTION_GID"
},
"projects": [
"PROJECT_GID"
],
"name": "Sample task name"
}
}
'
Note that while a direct text value (as a string) can be provided for text custom fields, the value for an enum custom field must be the GID of the enum option itself and not the text name of the enum option (e.g., the correct value is "1234567890", not "Option 1").
A similar process applies to updating a task as well.
Programming defensively
You should program defensively with regards to custom field definitions and types. For example, Asana users have the ability to change the definitions of custom field metadata in the Asana web app. Your app should account for this by double-checking that the custom field metadata are what your app expects them to be. Asana may also add new types of fields to the API in the future.
As you write scripts and apps that use custom fields, assume that the definitions may change at any time and that new field types may be returned. Failing to take this into account may cause your app to break or malfunction if it makes assumptions about the metadata for a particular custom field or if it assumes no new field types will be added to the API.
If your app stores a model for metadata, you should have a mechanism to dynamically update your model if it becomes out of sync due to the custom field metadata in Asana. For example, if you encounter an enum value on a task that does not match any option in your metadata model, your metadata model has become out of date with the custom field metadata and needs to be updated.
Enabled and disabled values
When information that is contained in a custom field value loses a logical association with its metadata definition, the value becomes disabled. This can happen in a couple of simple ways, for example, if you remove the custom field metadata from a project, or move a task with a custom field to a different project which does not have the custom field metadata associated with it. The value remains on the task, and the custom field metadata can still be found and examined, but as the context in which the custom field makes sense is gone, the custom field cannot change its value; it can only be cleared.
Custom field retention
Tasks that are associated with multiple projects do not become disabled, so long as at least one of the projects is still associated with the custom field metadata. That is, tasks with multiple projects will retain logically associated to the set of custom field metadata represented by all of their projects.
Moving the task back under a project with that custom field applied to it or applying the custom field metadata to the current project will return the custom field value to an enabled state. In this scenario, the custom field will be re-enabled and editable again.
In the Asana application, disabled fields are grayed out and not allowed to change, other than to be discarded. In the API, we return a property enabled: false to inform the external application that the value has been disabled.
Note that the API enforces the same operations on disabled custom field values as hold in the Asana application: they may not have their values changed, since the lack of context for the values of a custom field in general doesn't provide enough information to know what new values should be. Setting the custom field value to null will clear and remove the custom field value from the task.
Access control
Custom fields are a complex feature of the Asana platform, and their access in the Asana application and in the API vary based on the status of the user and project. When building your application, it is best to be defensive and not assume the given user will have read or write access to a custom field, and fail gracefully when this occurs.
Updated 9 months ago