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.
Nomenclature
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.
Timeline
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.
Timeline
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>/sectionsMigratedTowhich will return a list of sections (possibly an empty list), and -
GET /sections/<section-id>/taskOriginatedFromwhich will either the source task or a404 Not Foundresponse.
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.