Sections are dead! Long live sections!




Thanks for your response! This raises another question. Does this change only affect the board-view projects and list-view projects will follow at a later time?


@Benjamin_Ragan Actually board-view projects already use the formal object-based Sections so they are not changing at all. This upcoming migration applies only to list-view projects; it will convert their Sections into the Section-object-based model that boards use now.

Not to confuse things further but I should mention that Sections in subtasks and in My Tasks are the two places that will NOT be impacted by this migration. Those will remain as task-based sections. This is described more fully in this post and its accompanying thread.


@Phil_Seeman: Thank you for the clarification. We are using sections at the Project level, so we will be impacted by this change. I didn’t see anything in the documentation. Is there a way to test list-view section sorting (e.g. after_section) before a project is converted to the new Sections objects?

Our application which would create sections is automated and we need to be able to properly test before our projects are converted to the new Sections.


I don’t think there will be a way to test, but perhaps more info on that will be available as the Asana team moves forward with the migration. Be sure to read @Joe_Trollo’s initial post at the top of this thread for more on that; and I’ve @mentioned Joe so he might have some advice for you as well.


@Benjamin_Ragan: to test how the API will eventually behave after the migration, use a board-view project. Lists are moving to the boards data model so effectively what is happening is that we’re (1) converting all lists to boards and (2) providing a way to visually render boards as lists. From the perspective of the API, boards are “post-migration” projects already.


I like that way of thinking about it!


While I understand the technical considerations that require this change, the actual UI/UX implementation is severly lacking compared to the previous one.
One of the main reasons for us to move to Asana was the versatility - what feels like a simple list,
UX-wise, has actually sections, headers, subtasks… With the change, it feels like I’m back to working with an underlying database, which I don’t want to think about.

Here’s actual issues that you should fix:

  • not possible to toggle between section and back to task, which we are using a lot
  • not possible to first type, then decide that this should actually be a section - unnecessary additional work to copy+paste, then delete what I typed already
  • not possible to have a person assigned to a section, which we are using a lot as well - basically someone is responsible for the overall section of a project and we want to keep that
  • not possible to set due-dates for sections - same issue as above

Overall, I think you might not have a complete understanding of how people are actually using the sections feature in Asana so far.


Thanks, Joe, for your detailed response. Here is my suggested compromise.

Make a settable preference that lets me, when I am first typing a task, to convert it to a section by terminating it with a colon. It would be one-way (meaning: none of the back/forth conversion issues would exist) and it would essentially be a shortcut to Cmd+N for us users (me: I think maybe 6 years) that have colon-sections embedded in our motor memory. You could have this setting OFF by default so that new users won’t develop the habit but it would be a wonderful/acceptable compromise for us legacy users. The create-a-section-with-a-colon feature was, frankly, one of the most smooth and brilliant aspects of the Asana UI that converted me to use Asana years ago. Nothing else behaved quite like it.


Agreed! :slight_smile:


Couple comments:

  1. Removing the Colon functionality and only notifying users via a quick one-time pop-up was a mistake. I had to research how to set them up, and I’m a power user. I acknowledge that you can click “add section” at the top, but keyboard shortcuts are king, and to pull one out from us is puzzling.

  2. Are there plans to facilitate collapsing sections?

Thank you.


Hi James,

You may have seen this already but there is still a keyboard shortcut to add a section, it’s just different - now you use Tab+N.


It is coming, as part of the overall rework on sections.


Thanks Phil - I"m aware of the Tab+N, but having been in the habit of using a colon for years, it’s still not natural and wasn’t well advertised.


Bastien - That is terrific news! I’ve been asking for that for years.


Reminder: This forum thread is directed at developers using the Asana API. To facilitate separation of concerns, please limit product feedback to the the corresponding thread in the Product Updates category.

The API team has finished defining the API migration and has a final set of changes and instructions to share with our developers. These changes are available right now in the API, though some of them are gated by our deprecations framework. The name for this deprecation is new_sections.


From now on in the API, “section” refers exclusively to a proper column-section in our data model. The name for a task that happens to be rendered as bolded and underlined is "separator."

The changes

There are two product changes happening that have spurred on the API changes we’re about to enumerate.

1. Separators are no longer required to have a name that ends in a colon

This is the Tab + N change that is already rolling out. This change means that the name of a task alone cannot determine whether a it is rendered as a separator. To that end, we’re changing the available attributes on tasks to reflect this more accurately and cleanly.


The Tab + N change has already begun rolling out to users, and we expect that it will be fully rolled out to 100% of users by the end of February (but this is subject to change).

Separators in subtasks and My Tasks

Tasks with resource type: "default_task" have a new boolean field on them called is_rendered_as_separator. (This field is omitted by default but can be requested using the opt_fields parameter.) This indicates whether a default task is rendered as bolded and underlined when viewed in a list of subtasks or in a user’s My Tasks.

This field can be modified only if you have enabled the deprecation, and will control how the task is rendered in those contexts. Because the Tab + N change and the dissociation of separators and colons has not rolled out to all users yet, modifying this field may change the task name depending on the user’s status in the rollout. If the user does not have the Tab + N change and still has to use colons to make a separator, modifying this field will add and remove a colon as necessary. If the user does have the Tab + N change, modifying this field will not change the task name. Modifying this field always does the “right” thing for the user both before and after the migration.

Resource subtypes

Currently, separators will indicate that they have resource_subtype: "section". This will be deprecated in favor of is_rendered_as_separator and separators will instead have resource_subtype: "default_task". You can get this new behavior now by enabling the deprecation. Until you enable the deprecation, this field may be inaccurate as projects across Asana are gradually migrated. (Specifically, tasks may report resource_subtype: "section" even if they are in migrated projects that do not render them as separators.)

2. All projects will be migrated to the boards data model

In addition, projects that follow the boards data model will receive a “list” view where each column becomes a section in the list, similar to how list projects look today.


A select few alpha testers will be able to migrate projects starting within two weeks. We do not yet have a confirmed timeline for when we will extend the option to wider audiences, or when we plan to automatically migrate any remaining un-migrated projects.

Project migration status

Projects now have a new (but temporary) field called section_migration_status that will indicate the current section migration status for that project. The possible values are

  • "not_migrated",
  • "in_progress", and
  • "complete".

Note that boards projects will indicate that they have already completed the migration. This field will be removed about one month after all migrations have finished.

Interacting with projects during migration

While a project is being actively migrated, certain changes to it will be blocked. This includes:

  • Deleting the project
  • Inserting tasks
  • Removing tasks
  • Reordering tasks
  • Creating new separators
  • Completing or un-completing separators
  • Deleting or un-deleting separators

If you attempt any of these actions on a locked project, you’ll receive a 403 Forbidden error.

The vast majority of projects will take between a few seconds to a few minutes to migrate. Massive projects with tens of thousands of tasks or more may take over an hour to migrate, so please plan accordingly.

The layout field on projects

The layout field on projects is deprecated and will be removed from the project resource. You can get this new behavior now by enabling the deprecation. Until you enable the deprecation, this field may be inaccurate as projects across Asana are gradually migrated. (Specifically, projects that have been migrated will always claim layout: "board" even though users can view them as lists.)

The projects field on sections

The projects field on sections is being deprecated and replaced with a project (singular) field to reflect that sections will be in exactly one project. You can get this new behavior now by enabling the deprecation.

Extra support

There are a few API-specific changes we’re making that aren’t strictly required by the product changes, but may benefit developers and apps.

Linking old separators to newly created sections

In the event that your app manually tracks separators and needs to know what sections they spawned during the migration, we’ve added a new temporary endpoint that, when given a task, will return all sections that were created from it during the migration. (There may be multiple sections as a task can be multi-homed.) Similarly, we’ve also added a temporary endpoint that, when given a section, will return the task that it was created from, if any. (There may be no source task if the section wasn’t created by the migration.) These endpoints are

  • GET /tasks/<task-id>/sectionsMigratedTo which will return a list of sections (possibly an empty list), and

  • GET /sections/<section-id>/taskOriginatedFrom which will either the source task or a 404 Not Found response.

Note that the list of sections a task has created may expand as more projects containing that task are migrated. Also note that the separator tasks may or may not be deleted, either automatically by the migration (this is a pending product decision) or by users who are cleaning up their projects post-migration. Standard access control applies, and these endpoints will not return deleted tasks.

These endpoints will be removed about one month after all migrations have finished.

Iteration order of tasks in a project

For all projects, the iteration order will be top-to-bottom in the first section (or equivalently in the first column, they are the same now), and then top-to-bottom across sections (equivalently left-to-right across columns). We are currently building and backfilling the database index to support this ordering, and will update this post when that is complete.

Stages of this migration

As this migration progresses, users/projects will pass through a set of fixed stages. For clarity, those stages are:

  • List projects don’t use sections, separators are rendered as such and must end in a colon. This is the world we were in just last month.
  • List projects don’t use sections, separators are rendered as such and can have any name. This is the change that’s rolling out now.
  • List projects are undergoing active migration. This will be a (usually) brief window during which certain operations are forbidden in the migrating project.
  • All projects use sections, separators are not rendered as such in projects. This is the final world post-migration.

We need your help!

If you notice any oddities or peculiar behavior, please let us know. This is a complicated deprecation and we want to make sure that all issues are treated quickly to make sure this can be as smooth as possible for our developers. And, as always, feel free to ask questions in this thread if you need more clarification. We’ll be updating this post over time to reflect the latest situation and answer common questions.


Hi @Joe_Trollo, and thanks for all this work and for this well-written post.

I’ve started to use some of this and so far so good (but I still have more to do).

I wanted to ask about one thing related to:

But new_sections is not mentioned in the Active Deprecations table in deprecations framework. So far I’ve enabled new_task_subtypes, which is listed in the table, and I do see some of the changes mentioned in this post.

So can you explain/reconcile these two deprecation names for me (us)?

I’ll reply again when I develop another question or issue, or let you know if I’m able to get Asana2Go changed so that it works now and during all phases/states upcoming.




@Joe_Trollo, One more question–do you have a determination yet on the following:


The content in this thread is the newest information available, while updates to our documentation need a review cycle, build step, and deployment. The table you’re referencing will be updated soon.

The product teams have not yet made a decision about what will happen to tasks not already underneath a separator.


I just wanted to thank you, @Joe_Trollo, for exposing is_rendered_as_separator a couple of days ago in response to my, and others’ request (mentioned in the now-closed post: “Tab+N” new shortcut to create Sections).

I just rolled out an update to Asana2Go earlier today so that it works fine once again after the changes to the product made earlier last month.

I know this is a product issue, not an API team issue, and I understand how Tab-N and the removal of “:” needed to precede a lot of other work for you all there, but springing that without warning or recognition of some key implications has been and continues to be a hardship. We still can’t create sections on mobile, right? Exports can’t tell what’s a section and what’s a task. And in my particular case with Asana2Go, this change caused a lot of time to figure out what was going on, request and wait for an API change (which again I greatly appreciate, and was done in just three weeks start to finish), then implement it, all unplanned. I know this isn’t common, and you all work hard to prevent it, but I hope future changes are vetted more deeply internally, or more inclusively.




Maybe they’ll come up with a shortcut to change the task to a “column-section”, such as Ctrl+? marks a checkbox. I agree that it’s such a great feature for inputting task lists.