[New] ID custom fields

English Forum Developers & API Changelog
,
1

Summary

Asana recently released ID custom fields as a way for users to uniquely identify tasks both within and outside of Asana, which is especially useful for ticketing apps.

More details about custom IDs:

  • ID custom fields can be added to any project and will automatically generate incremental IDs for both existing and new tasks.
  • ID custom field values are immutable and unique to the entire domain
  • Projects and tasks can have more than one ID custom field
  • Users will be able to find a task using a ID custom value
    • Allowing users to retrieve a specific task by this shorter and more memorable identifier
  • The custom field API has also been extended to return the ID custom fields and their values similar to how other custom fields are returned
  • For the initial API release, we will not allow users to create an ID field or modify the prefix of an existing field via the API

Usage

Here’s an example of fetching the custom fields for a task in a project that has a custom ID field:

GET /tasks/<task-gid>?opt_fields=custom_fields

Returns:

{
  "data": {
    "gid": "1206585912264092",
    "custom_fields": [
      {
        "gid": "1206627874171841",
        "enabled": true,
        "name": "BIZ",
        "description": "Custom id for business ticketing system",
        "created_by": {
          "gid": "180015866142448",
          "name": "Max Powers",
          "resource_type": "user"
        },
        "display_value": "BIZ-76",
        "resource_subtype": "text",
        "resource_type": "custom_field",
        "text_value": "BIZ-76",
        "is_formula_field": false,
        "is_value_read_only": true,
        "type": "text"
      }
    ]
  }
}

Who is affected

This new field affects apps fetching custom fields via the API. If you have programmed defensively to account for new custom field types, as we recommend in the docs, there will be no impact since existing responses have not been modified.

Timeline

ID custom fields are live in Asana and reads are live in the API. Based on developer feedback, we may add additional API features in the future.

Questions & feedback

Custom IDs empower developers to build ticketing apps and integrate with other ticketing solutions. We’re excited to hear your feedback and answer any questions you may have.

Happy coding!

6 Likes
2

Thanks, @Jeff_Schneider.

I just tested and this is working in Asana2Go now!

Larry

2 Likes
3

Hi @Jeff_Schneider,

I’ve noticed there is a new property on custom fields, representation_type. It’s equal to the resource_subtype for all custom fields except that it’s set to formula and custom_id for those special cases, making it a really nice way to tell within just one property both what the field type is and also if it’s one of those 2 special cases.

Is representation_type an “official” property that we can safely use with the API? :pray: :pray:

3 Likes
4

Yes, representation_type is a stable field that won’t change. Good to hear the new properties have improved the developer experience.

3 Likes
5

Excellent news, @Jeff_Schneider, thanks!

Maybe we can get it added to the developer docs?

2 Likes
6

This may be a lot to ask, but could someone provide a use case for this (in simple terms). For example: Client has a request …Add the request to Asana task…

I feel like this solution could actually make something easier for our project manager, but I’m not exactly sure how lol. Sorry. Genuinely appreciate the help!

1 Like
7

@Phil_Seeman thanks for catching this. While representation_type is documented as an opt_fields for get a custom field, it was missing from the custom fields schema. We just added it. The change will be reflected soon in the reference docs and it will look like this:

Add representation_type
Add representation_type1424Ă—1375 253 KB

3 Likes
8

@Russell_Silberman I suggest reviewing the ID custom field announcement in the product updates section of the forum. Two of the primary use cases for custom ids are requests (e.g. creative requests submitted with a form) and ticketing (e.g. IT support).

This API changelog post is for developers build apps and integrations with the custom ID field API. For example, integrating a ticketing app with Asana tasks that use custom IDs.

1 Like
9

Thanks! I somehow brushed over that announcement