tl;dr: We are making breaking changes to the way that user task lists (i.e. My Tasks) work in the Asana API. If your app interacts with user task lists, please read!
Hi there!
My name is Yacob Yonas and I am a Engineering Program Lead here at Asana. I am here to tell you about some updates to our My Tasks API coming in early March. Last we spoke about this topic there were concerns about changes to My Tasks functionality. We have heard this feedback and made changes to reflect that. Below you will find details on what is changing, why we are making the changes (including plans to preserve the ability to move tasks between sections automatically), and a timeline for these changes. So let’s jump into it!
What is changing from an API perspective
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 deprecated to make way for a new version of these sections that is customizable. (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.
- 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 string attribute: user_task_list.migration_status; it is an string with 2 valid values: not_migrated or completed. 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}orPOST /tasksendpoints 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 name of the deprecation is new_user_task_lists so as per our deprecation documentation , you can opt in to the new behavior by passing the following header in your requests: Asana-Enable: new_user_task_lists
Why are we making these changes?
Asana has been rebuilding My Tasks for several months in order to add exciting new features. These features will allow each individual to customize their view. We realize that many users care deeply about the existing Today / Upcoming / Later sections and the auto promotion of tasks that happens from Later to Upcoming and Upcoming to Today. With that in mind, we are working to build that functionality into the new My Tasks so individuals can continue to manage work in that way.
When should you expect to see these changes reflected in the API?
You can opt-in using the deprecation flags today! This opt-in period will run until all task lists have been migrated. These changes will impact the API in two phases:
- When we roll out these features to new My Tasks users (scheduled for early March)
- When we migrate existing users (scheduled to start at the end of March). We will let you all know the exact dates as they become finalized.
Stay tuned for more to come in the next few weeks. Looking forward to your feedback and questions!
thanks for the detailed update 
yay! Thanks!