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.
Update: We have made the final migration plan for this deprecation, which you can read in further down in this thread.
Hi everyone, I’ve got some good news and bad news about sections in list projects. The bad news is that we’re killing them, but the good news is that they’re coming back better than before! To summarize (because this is a very long post) we’re changing how sections work in our data model for list-view projects, which means the API is going to have a radical shift in how sections behave and how developers can interact with them. Sections are not going away! While the API will experience a disruption, the Asana web app will continue to have sections throughout this change.
A brief history: currently, “sections” in list-view projects are just tasks whose names end in a colon. (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. Meanwhile, columns in a board-view project (“column-sections”) are a separate type in our data model that do have explicit containership for the tasks within them.
In order to solve many usability issues with sections in list projects and pay down the technical debt of having these fake task-sections, Asana is deprecating them in favor of column-sections. Engineering teams here are already working on how this migration will play out, but it will have specific implications for the API. Below, we’ve broken them down into two groups: breaking changes and improvements.
Task-sections will no longer have special meaning. Currently, a task-section’s
resource_subtypeattribute in the API will read
"section", but they will eventually become standard tasks with
Projects will no longer have a
layoutattribute. This data model change means that the association between tasks, column-sections, and projects are now indistinguishable between board and list layout. (This, in turn, opens the way for a particular, highly-requested product feature… )
Task-sections will be replaced with proper sections. The migration process will take each task-section 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, users may delete any old task-sections on their own.
Section endpoints will start working for all projects. Currently, the
GET /sections/<section-id>/tasksendpoint only works in board-view projects because column-sections exist only in one project. The column-sections that replace task-sections will also exist only in one project, opening up this endpoint for all sections.
Iteration over board projects will be intuitive. If you list all the tasks in a board-view project, they’ll be returned in an order based on when they were inserted into the project (with most recently inserted tasks first). After the migration, they’ll be in the intuitive order: First top-to-bottom in a column, then left-to-right by column.
Moving a section will move all tasks in that section with it. This is similar to how you would move column-sections in a board project.
There is one aspect to this migration that will make it especially difficult: this migration is not controlled by the API team at Asana. Rather, individual users will be able to trigger the migration of their own projects when they want, and that ability will be gradually rolled out. The migration of a given project will also take anywhere between a few seconds and a few minutes to complete, during which the project cannot be interacted with.
The deprecation plan:
Using the deprecations framework, the following new behaviors will be exposed:
layoutattributes on projects will cease to exist.
GET /projects/<project-id>/sectionsendpoint will only return column-sections and never task-sections. This means that, when you look at a list-view project prior to the migration, it will appear to have no sections. Once the migration occurs and the project is given column-sections, those column-sections will be returned automatically.
When looking at a task-section, it will have
resource_subtype: "default_task". This means that task-sections will be indistinguishable from normal tasks.
Additionally, projects will be given a new, read-only enum attribute called
section_migration_status which will be one of
"completed". This will be a temporary field that will be removed about one month after all projects in Asana have been migrated and should not be considered a permanently supported addition to the API, so integrations using this attribute should be built to handle its absence. Board-view projects will appear to have already migrated and will have this field set to
"completed". The presence of this field will not be controlled by our deprecations framework.
Some developers may not want to opt-in to this deprecation early, as it will remove some functionality around task-sections before it gets fully replaced with column-sections. Because of this and a few other constraints, the API deprecation period will overlap with rolling out the in-product migrations. This means that your apps may encounter a migrated project before you opt-in to this change. This also means there will be no opt-out period. Because this is happening at the level of the data model, once a project has been migrated it will not be possible to replicate the old behavior.
The opt-in period will begin fairly soon (before any projects are actually migrated) and will run until all projects 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.
When a column-section is created, how do I know what task-section it came from? Or, when looking at a task-section, how to I know which column-sections were created from it?
We’ll temporarily expose endpoints that, when given the ID of a column, will tell you which (if any) task it came from. Similarly, if you give us the ID of a task, they will tell you which columns (if any) were created from it. (Note that, because a task can be multi-homed, a single task-section can result in the creation of several column-sections.)
How should I react to this change?
There are a several options here, but here are three high-level paths you could take:
You could opt-in now and have your app believe that the new world is the only world that exists. This should require very little code change and your app is guaranteed not to have unexpected behavior throughout the migration, but you will be missing functionality around sections until the relevant projects are migrated. This could lead to feature-incompleteness for your app or workflow.
You could write code to handle both migrated and unmigrated projects, and act according to the migration status field on the project. If your app relies on manipulating sections to work properly, this is likely the path you’ll have to take. You’ll be able to operate normally for your users throughout the entire migration period, but you may need to invest significant effort into these duplicate code paths. (If you currently handle board-view projects, though, you’ve got the code already!)
You could do nothing! Depending on what your app does, you may not be affected by this change at all.
Here are some more specific hypothetical examples of apps and how this deprecation would affect them, along with the changes they might have to make.
If your app takes all the tasks in a project and returns the name of each section and the number of tasks in it, then you do not need to do anything. Prior to migration, tasks in a project will have (fake) membership to the task-section above it. After the migration, the tasks will have a real membership to the column-section. At any point, looking at the
membershipsattribute of the task will correctly identify the section the task is in, and calling
GET /sections/<section-id>will return the correct name.
If your app takes all the tasks in a specific section, identified by ID, you’ll need to check for when the project has been migrated, and then get the ID of the column-section created for the previous task-section. Then while you can continue to fetch all the tasks in the project and look at their memberships, you should have your app call
GET /sections/<section-id>/tasksto get just the tasks in the new column-section.