Sections are dead! Long live sections!

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.

3 Likes

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.

1 Like

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.

2 Likes

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

2 Likes

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

7 Likes

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.

Thanks,

Larry

1 Like

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

1 Like

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.

Thanks,

Larry

4 Likes

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.

Hi,

Not sure if im missing somthing. I tried to create a subtask with the field is_rendered_as_separator: true but that didnt create a subtask-section. Is it possible at this moment to create separators on a subtask or should that be created on a section endpoint to the apI?

Thanks!

@Jonas_O, I haven’t tried setting the field myself (only getting it), but a quick possible cause to confirm: Are you positive you have enabled the deprecation header when trying this?

2 Likes

@Joe_Trollo - Thank you for keeping us up to date. However, I still have not received an answer to how to sort sections within the new Sections framework. We have a process which would create Sections in Alphabetical order and then tasks under the correct section. The sorting of the sections is critical to our workflow under this project.

We currently are able to do this by using the Task API on projects which have not been converted to the new Sections interface. The documentation for new Sections does not allow for sorting. Additionally, I created a Board Project and attempted to use the “section” and “insert_after” option (both listed under the task API and were referenced ealier in this thread as possible options) when creating a new section but had no success.

Please provide thoughts on how to insert of Sections in Alphabetical order with the new Sections API.

If this is not an option, it will break our current workflow and make Asana unusable.

Thanks for your feedback!

1 Like

Hi @Benjamin_Ragan,

Did you try this endpoint with the before_section or after_section parameter?

@Phil_Seeman - I tried “after_section”. It does not appear to work when creating a new Section. This appears to move a section after the Section has been created. This would require 2 calls, which can be done, but is not ideal.

If I am missing something, please let me know.

I haven’t tried it myself but there is a specific example on that page of adding a new section and including before_section in the insert call (it’s under “Add or move a section in a project”); maybe try that to follow that example and see if you can get that to work?

Thank you for your feedback. I agree there is a heading Add or move a section in a project, but the example assumes the call already has a gid for the section.

curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/sections/insert \
--data-urlencode "section=2001" \
--data-urlencode "before_section=2002"

This would indicate the section was already created prior to adding to a project or moving within a project.

Any other suggestions, other than making two separate calls API calls (Create the Section then Move the section)…

Again, thank you for your help.

1 Like

Good point! Time to call in the cavalry.

@Joe_Trollo @Matt_Bramlage @Jeff_Schneider: is there a way to add a new section in a particular location within a project’s sections, or do you need to add it first, and then do a second call to place it?

Hi @Benjamin_Ragan, the API should support insert_before and insert_after when creating a section, but upon inspecting our code I found a bug which was ignoring these parameters. The fix should be deployed in another day or so, after which both POST /sections and POST /projects/<project-id>/sections will accept insert_before and insert_after.

6 Likes