Upcoming changes coming to My Tasks in Asana and the API! [breaking changes]

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.

  1. 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.
  1. 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/tasks will 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>/tasks endpoint 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} or POST /tasks endpoints 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 via opt_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:

  1. When we roll out these features to new My Tasks users (scheduled for early March)
  2. 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!

7 Likes

@Yacob,

Thanks for the detailed post.

It’s sounding like Asana is now committed to replacing Marked For and Auto Task Promotion, but not exactly indicating:

  • how Assignee Status will be retrieved from the API (now on sections but not on tasks as before?), and
  • when this will be possible.

What I think this means is that you are telling us that there will be a period, starting in March, when Marked For and Auto Task Promotion go away for users as they are migrated, and goes away for apps that work with Assignee Status, and there’s no information on how long that period will be, and exactly what it will look like when it comes back. Is that correct?

I feel my comment from October related to these changes still applies:

Also, recently it was pointed out that not just GET and PUT are affected, but also POST, so shouldn’t you include that in this post too?

Thanks,

Larry

1 Like

Hi @Yacob,

Thanks for this update!

Just to underscore what @lpb says above, what we really need to know is how to programmatically use whatever will be replacing assignee_status.

1 Like

Thanks for your questions, @lpb! To clarify, we have been hard at work on an amazing improved My Tasks experience. We plan to let new users have access to this experience before the migration of existing users takes place, minimizing new user confusion of switching a screen days after onboarding. This means that for a couple of weeks, new users will not have access to auto-promotion. During that time, we will be building auto-promotion functionality for the new My Tasks.

By the time existing users are migrated to the new version of My Tasks, Today / Upcoming / Later functionality will be available. Existing users, like yourself, will not see interruption to your workflows.

Also, recently it was pointed out that not just GET and PUT are affected, but also POST, so shouldn’t you include that in this post too?

That’s a good callout. Just edited the post above to make clear that POST /tasks is impacted as well.

1 Like

what we really need to know is how to programmatically use whatever will be replacing assignee_status .

To answer your specific question directly, there will be no special My Tasks concept of a assignee_status anymore after the migration. If you want to move tasks around, you should use the same endpoints you would use in projects to move a task in or between sections.

Yay! :grinning: thanks for the detailed update @Yacob!

Thanks for that clarification, @Yacob! But what about auto-promotion? Currently auto-promotion is somewhat tied into assignee_status; how will we interact with auto-promotion programmatically in the new model?

1 Like

Fantastic, @Yacob! Thanks for clarifying and for the incredible juggling act you’re contending with given all these changes. I really like that decision to avoid interruption for the many existing users, and hope the brief new user experience is manageable. We’ll all be here to help those new users adjust as needed!

Larry

I think many users are very concerned about losing the ability to set something to “Later” (or whatever it’s called) and have it auto-promote based on the due date so it’s not forgotten in the future. Another concern is losing the “Recently Assigned” or triage area.

I saw you posted that Asana has “plans to preserve the ability to move tasks between sections automatically.” But I have fears based on recent changes that Asana will bundle this ability with Rules behind the Business Tier paywall.

@Yacob, can you please help me sleep at night and clarify if all users will have the ability to set tasks to autopromote through sections/columns based on some kind date setting?

5 Likes

@Todd_Cavanaugh you can sleep safely at night knowing that users from all tiers will still be able to benefit from auto-promotion functionality.

7 Likes

:clap: yay! Thanks!

1 Like

Follow up

As an FYI, we plan to launch the new My Tasks experience (explained in the top level post above) to new users starting early next week (aiming to start on Monday 3/8).

Once we start rolling out to new users, your apps may break in the aforementioned ways for these users if you haven’t prepared for deprecation. The existing user migration is still weeks away and we will give another ping here when we are a week or so out.

7 Likes

A post was merged into an existing topic: [Upcoming product update] My Tasks v2 :fire:

I think it’s a shame that sections/board columns weren’t simply a selected custom field. This would give flexibility in the my tasks list and board view. I had hoped myTasks would have some additional perspective functionality, rather than just mirroring standard project views.

Good day.
When the update in the section my tasks will appear for old users.

Hi @Максим_Больных, please find more information and the dates in our recent announcement: Meet your new My Tasks

Another timing update

As I mentioned above, we have launched this new My Tasks experience to new users as of 3/8. We’re finishing up work that will enable us to begin our global migration to bring all existing users onto My Tasks v2. We hope to begin this migration in 2-3 weeks. I’ll post here once we formally begin.

2 Likes

I’m still trying to test my Asana2Go with My Tasks v2 and understand I should create a new user to get v2. Is it rolled out to 100% of new users now so i can be sure I’ll get it if I create a new user for this purpose today?

Thanks,

Larry

Today, only a percentage of new users will get v2 currently. This is expected and we will be going to 100% in the next week or so.

@Yacob,

Thanks for the reply. Actually, just a couple of hours ago a brand new client just added me (my main email address) as a Guest in their organization and that gave me the new v2 experience there (but left it as the v1 experience in my existing organizations).

So that means it’s not only being rolled out to new users; I’m an old user (!) and in an old (client’s) organization, but that combination resulted in the v2 for me; I wasn’t expecting that. But that’s fine since I wanted to see it anyway. Maybe by “new user” you meant a new Member/Guest, even if not new to Asana overall.

And I’m happy to see that Asana2Go works fine w/o changes (but I have to test more).

Larry