Sections are dead! Long live sections!

English Forum Developers & API
,
1

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.

Breaking changes:

  • Task-sections will no longer have special meaning. Currently, a task-section’s resource_subtype attribute in the API will read "section", but they will eventually become standard tasks with resource_subtype: "default_task".

  • Projects will no longer have a layout attribute. 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… :wink:)

  • 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.

Improvements:

  • Section endpoints will start working for all projects. Currently, the GET /sections/<section-id>/tasks endpoint 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:

  • The layout attributes on projects will cease to exist.

  • The GET /projects/<project-id>/sections endpoint 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 "not_migrated", "in_progress", and "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.

FAQ

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 memberships attribute 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>/tasks to get just the tasks in the new column-section.

18 Likes
3

Finally! :slight_smile:

My head hurts. But I think this all makes sense. Will have to read it over a few dozen more times to be sure…

4 Likes
4

@Joe_Trollo You may not be able to confirm or deny anything but could this possibly, hypothetically, according to a friend of a friend, be the first step towards the ability to switch between lists and boards?

23 Likes
5

@Mark_Hudson looks like it :grimacing:

8 Likes
6

for those of us not using the API, how will this impact how section are used in the UI?

12 Likes
7

It was time for this but I will start crying :stuck_out_tongue:

3 Likes
8

Very, very hopeful of some benefits to be reaped from this change in the data model.

1 Like
9

As someone who signed up to Asana in the last couple of weeks, it’s unclear to me whether this change has already applied to all of my projects or if I have to opt in. If I have to opt in, it’s unclear to me how to do so.

1 Like
10

Hi Gabriel!

First, no this change hasn’t been applied to your projects yet - it’s something that’s coming in the future, with no specific timeframe provided yet.

Second, the opt-in that’s described here pertains to developers using the Asana API, not to end users. Are you developing with the API? If not, there’s no opt-in to do and I wouldn’t be too concerned with this forum post; when this change to sections comes, you’ll know about it as an end-user, and anything you do in Asana now will transfer over once the change is made.

3 Likes
11

This is very good news. I was intending to write yet another post on everything wrong with sections. I’m glad Asana will finally fix the issues you described, @Joe_Trollo. I’m so excited to see that the developers will see sections (titles) as something more than simple placeholder tasks, making it easier to group related tasks within one project.

3 Likes
12

Very excited about this migration!

13

I presume sections will also collapse/expand?

6 Likes
14

@John_Douglas, @Gabriel_Gallagher, @Chad_Funk: our engineers are still working out how this will impact the UI and behavior of the web product. Currently, I only have information about the changes to our underlying data model and Asana’s API.

2 Likes
15

Hopefully it will be collapsible also in the Timeline view to get a visual according to a Gantt chart (like seen in MS Project). :crossed_fingers:

1 Like
18

How will this affect tasks not in a project? Specifically, what happens to the sections in “My Tasks”?

4 Likes
19

@Scott_Abbott: Tasks not in projects continue to be just tasks—in the new data model, a section cannot exist outside a project. We don’t yet have any specific information about how task-sections in a user’s “My Tasks” will be migrated.

2 Likes
20

Nice update. Can’t wait for that highly requested feature.

(This, in turn, opens the way for a particular, highly-requested product feature… :wink:)

21

What about section-less tasks? Will you create a “default” section to add them to? And if I have some tasks without section, followed by tasks in-section in the same project, will you add a new “default” section, at first position, then followed by new converted sections?
Actually, we can edit the task to remove its section membership, for tasks in a list-project. But we can’t in a board-project.

4 Likes
22

If columns are becoming mutually exclusive, it would be a great value add to include the column in the reporting outputs.