tl;dr: We are making breaking changes to the way that user task lists (i.e. My Tasks) work in Asana. If your app interacts with user task lists, please read!
Hi everyone,
I’m Yacob and I’m a Product Engineer here at Asana. I’m here to share some exciting news about some upcoming changes we have to the My Tasks (a.k.a. user task list) experience and let you all in the developer community know about the changes we will be making to our API to support this new experience.
First, some background!
Today, in user task lists, there are 2 primary ways you can group and organize your work.
- All users have 4 default priority sections (Recently Assigned, Today, Upcoming, & Later)
- Users can move tasks around between those priority sections manually and additionally, we have a process called “task auto-promotion” that moves tasks automatically between these sections based on task due dates.
- Users can manually create “sections” in their user task list to further organize, and these manually-created “sections” live in one of the 4 default priority sections.
- These “sections” are just tasks with a specific bit of metadata to allow them to display visually as separators. To disambiguate these later, they will be referred to as “task-sections”.) Because it’s just a task, at the level of our data model it doesn’t actually “contain” the tasks that come below it.
We’re excited to announce that we are giving users the ability to completely customize the structure of their user task list by introducing “column-sections” in user tasks lists, much like they exist in projects. We believe that this will allow users to view & structure their work in whatever works best for them; this means the ability to switch between board & list view, the ability to have proper “column-sections” that act as containers, and the ability to control how they want to group their tasks.
To that end, Asana is deprecating “task sections” and these 4 default priority sections in favor of these “column-sections”. As you might expect, with a change like this, the API will undergo a radical shift in how sections in user task lists behave and how developers can interact with them. So I’m here to tell you all you need to know about how this will impact our API.
We will break down the implications of these changes on the API into 2 chunks: breaking changes & improvements.
Breaking changes:
- Task-sections will be replaced with column-sections. The migration process will take each task-section (except ones that exist in the “Later” category) and create a new column-section to replace it. The old task it came from may or may not remain behind, depending on the final migration process. Additionally, after the migration, users may delete any old task-sections on their own.
- The 4 default priority sections (Recently Assigned, Today, Upcoming, Later) will be going away. (We will refer to the property corresponding to these sections as assignee status for this post). Therefore, we will not allow writes to this property and we will stop returning this property when returning metadata about tasks. In addition, task auto-promotion will be going away as well!
- The order of tasks returned in user task lists from the
GET /user_task_lists/:user_task_list_gid/taskswill change to return tasks in order for each column from left-to-right. - Endpoints that allow users to read or write to the order or organization of tasks in a user task list will now only be accessible to the owner of the user task list. This includes endpoints that allow reordering tasks, moving tasks between sections, and modifying sections.
Improvements:
- Section endpoints will start working for all user task lists. Currently, the
GET /sections/<section-id>/tasksendpoint only works in projects today because task-sections are not true containers in user task lists. Column-sections will replace task-sections in user task lists so you will be able to use section endpoints on user task lists. This includes the ability to fully customize the names, order, and number of column-sections in user task lists. - Moving a section will move all tasks in that section with it. This is similar to how you would move column-sections in a project today.
In the future, we will kick off migration of a small number of user task lists, then ramp it up gradually, and over the course of months, we will migrate all user task lists. This means that you will not be able to opt-in or opt-out to signify when you would like this change. Rest assured, we will give you all a heads up as we get closer to the date when we kick off the migration!
The deprecation plan:
User task lists will be given a new, read-only boolean attribute called user_task_list_is_migrated, which will be true if the migration is complete for the given user task list and false otherwise. This will be a temporary field that will be removed about one month after all user task lists in Asana have been migrated. This should not be considered a permanently supported addition to the API, so integrations using this attribute should be built to handle its absence. The presence of this field will not be controlled by our deprecations framework.
Using the deprecations framework, we will be making the following changes:
- If an app calls the
PUT /tasks/{task_gid}endpoint with an assignee_status,no changes will be made to the assignee_status property. - If an app calls the
GET /tasks/{task_gid}endpoint or any endpoint that returns metadata about a task, we will no longer return the assignee_status property in the response payload, even if it is explicitly requested viaopt_fields
The opt-in period will begin fairly soon (before any user task lists are actually migrated) and will run until all task lists have been migrated. We will have a specific start date to share with you as soon as we’ve confirmed our timeline internally, expected within the next month.
Please let us know if you have any questions about this. We’ll be watching this thread for questions and will update this post as necessary to provide more information or clarification.
