Oh, man, yes, this is unfortunate I’m going to leave any technical details on how to move forward to @Joe_Trollo as he’s far more capable of holding the whole state of Asana’s data model in his head than I, especially during these times of transition.
What I would like to throw out there is the reason that you’re seeing the Tab+N change: y’all know this old thing? Switching from Boards to List View (and vice versa)? More or less the most-requested product enhancement in the Asana forums?
We’re fixing that this year in Asana and it will become possible to switch views between board and list projects.
The feedback in the above comments is really helpful in highlighting how seemingly minor changes (from our internal perspective) can have major impact for our integrations. We do our best on the platform team to keep abreast of these sorts of changes to flag breaking changes for our apps, and we’ve made a lot of progress in working with product teams to raise awareness of the impact of these sorts of changes, but sometimes these systems and changes are so complex that these apparently minor tweaks have a large impact, particularly for our API developers. We’re sorry about the negative effect this has had, so I’d like to peel back the hood a bit to explain some of Asana’s internals to make it clearer why this change was made.
How did we get here?
It would seem like switching between a board layout and a list layout would be relatively straightforward - and it should be - except that there’s historical data model technical debt that has to be paid down to make it happen.
As @Joe_Trollo mentioned in Sections are dead! Long live sections!, sections in list projects are implemented as tasks. More specifically, they are tasks that, when their name ends with a colon, tell the Asana data model that they should be rendered as a section. Joe called these “task-sections”, so we’ll call them that here. For further clarity, the colon is not significant for determining that a task is a section - as Joe mentioned, this is a property on the task that is not exposed in the API. A colon simply triggers this property to record the task should render as a section.
When they were originally built, sections as a container wasn’t the primary use case for them (they could represent a checkpoint, say, with no container semantics), but after gathering enough data about how sections are used, it became clear that the “containership” use case was their stickiest use. In fact, shipping task-sections fast was a very valuable way to improve the product while gathering the sort of usage information we wanted to determine what the value of sections is to our users. The point is, over time we’ve learned that sections work well as containers and we’ve built quite a bit of code to handle task-section containership seem like it’s a “real” thing.
Knowing this when boards were built is why our boards view did made columns a first-class data structure that contain their tasks. Let’s call these column-sections.
With these two different data models for our projects, we can’t switch between board and list projects very efficiently; we’d have to do some operation to keep two different data model copies in sync in real time. This would be yet more code to work with the task-section data model that we don’t want to keep encouraging to exist
That’s why we’re back-porting column-sections to list projects.
What is Tab+N?
The first change that the product team has made during this transition is to make task-sections behave more like their upcoming column-section implementation. You may notice that columns in board projects currently don’t have to have names which end in a colon, and this will be true for list views’ column-sections in the future. Additionally, Tab+N now creates a new section at the end of the current section in a list project, just as it will in the future with a column-section. (Previously, ending a task with a colon used to convert it to a section, and it would immediately start to “contain” the tasks below it. Now, with Tab+N, a new empty section is created after all the tasks in the current section).
Although list view sections today are still task-sections, the move to Tab+N from a terminal colon is meant to start our users’ behavioral migration now - to get people used to the fact that list view sections must behave this way when they’re implemented as column-sections.
So what’s going to happen with task subtasks?
For now the team that is focusing on the section migration is focusing on projects. That means that subtask sections will more or less remain the way they do today as task-sections (with the Tab+N behavior) for at least the near future, because that “feels” to our users like sections are consistent regardless of how they’re implemented, both during this transition and throughout our product. At this point in the process you can’t assume a terminal colon is the way to determine the section-ness of a task. Rather, for subtasks you should look at resource_subtype
to determine this information.
More changes will follow as we make this migration, some of them visible to Asana users, many invisible or nearly so. Unfortunately, it’s the nature of an API’s close access to its data model to be more exposed to these kinds of otherwise internal changes, so we have a harder time insulating our developers from any of these changes. Even when we try to anticipate some of them we’ll miss some and some might sneak under our radar, and even more challenging, some of them can’t be made invisible to our integrations. Thanks for your patience and understanding while we try to do our best to keep our API stable as we make changes behind the scenes.
Regarding the Tab+N change, we can’t roll back from this point, because Tab+N sections really don’t have a terminal colon, and a “rollback” would modify user-created data, which we only to do if it’s a big security concern. At this point we’re stuck in the new world, I’m afraid. The best we can offer is to assure you we’ve highlighted this as a zero-day API breaking change for our product teams to stay aware of the impact of changes made to Asana.
So here’s where we are today:
- Boards use column-sections; the endpoints in our docs that are boards-only (like reordering sections with POST /projects/{project_gid}/sections/insert ) only work on boards layouts.
- Lists use task-sections; they need not end in a colon, but they will have the
resource_subtype=section
property to determine that they are a section and not a task. - Subtasks use task-sections; they need not end in a colon, but they will have the
resource_subtype=section
property to determine that they are a section and not a task.
Here’s where we are after all projects use column-sections:
- Boards use column-sections, and the boards-only endpoints will continue to work for boards projects - with improvements. For instance, we’ll get better iteration order over tasks in a boards view; instead of semi-random, it will become top-to-bottom per column, left to right across columns.
- Lists use column-sections, and the (today) boards-only endpoints will start to work for them - you can bulk-move whole sections relative to each other in a list section, for instance, just like reordering columns in a board view.
- Subtasks use task-sections just like today. They don’t have to end in a colon and will no longer claim they are sections in
resource_subtype
; they will haveresource_subtype=default_task
. This is to reinforce that they are tasks and will show up as plain old tasks in all projects, both list and board view. (The analogy with the world of today is how a section, when moved/multi-homed to a board view, shows up as a plain old task in the board view; it’s really a task when you look closely at it). Joe and the API team are focusing right now on how to handle this case so apps can determine subtask sections in the future.
There are a number of edge cases in this future state that are frankly no worse than the edge cases in the current state, but they will be new edge cases. @Joe_Trollo is working with the API team and product teams to figure out how we might better head off these edge cases with new features or properties in our API, so stay tuned for updates from him.