Reminder about two big upcoming API changes (String IDs and new sections)

English Forum Developers & API Platform News
1

Hello, Asana developers! We are a short time away from some major changes in Asana’s API that will have a big impact on every Asana integration and we want to call your attention to them again.

Numerical IDs are being deprecated

We are approximately less than a month away from requiring string IDs by default for resources in Asana, yet the vast majority of integrations are not selecting a behavior for handling resource ID.

If you are unsure whether your integration is fully prepared to support string IDs everywhere and to use the gid field exclusively, your integration will break. Note, in particular, this includes the resource ID we return from our webhooks which need to be configured inside of Asana in our developer console.

However, it’s possible to prepare now! You can read more about how to have a smooth transition in our documentation for deprecations and learn why we are making this change in our article on moving to string IDs.

The current default API behavior allows the use of either string IDs or numeric IDs, but on August 13 we will change the default behavior to require string IDs in our API, so let’s get ready by then!

Sections data model is changing

Asana is moving to a new data model for sections that enables users to view all projects as both a list and a board. This has been our most-requested improvement for a long time so we’re excited to roll it out, but the nature of this change is that it might be a fairly complex process for our integrations.

The future state is that all projects will behave in our API just as board-layout projects do today. For example, working with sections in board-view projects in our API requires using the /sections endpoint, and board-layout sections are not returned when getting tasks in the project.

Both of these behaviors will become the new reality for list-view projects by the end of this transition. If your integration assumes that sections can be fetched from the /tasks endpoint or looks for tasks with names that end it a colon it will break during and after this transition. In addition, for the duration of the transition integrations must be prepared to handle data representing both the old and new state.

This complexity arises from the migration process itself. Asana will migrate existing old-style sections to new-style sections on a gradual basis, one domain at a time, between late May and throughout the fall. Integrations can’t manage or control the timing of this migration. Integrations must be ready for handling a project that is in one of and/or actively changing through these states:

  • The project is not migrated and has old-style sections if it’s a list layout.

  • The project is being migrated and is read-only; its sections will be actively changing during this time. Most projects will be in this state for a few minutes, but some very large projects might take longer.

  • The project has been migrated and has new-style sections and always behaves like a board-layout project.

The best way to prepare is through these two actions:

  • Ensure your integration works well with board-layout projects.

  • Ensure your integration can handle an in-transition project appropriately.

We’re using our deprecations framework to make list-view projects behave more like board-view projects, but this migration is unusual in that integrations can’t control or toggle the state of the project at any point in time. A feature of our deprecations framework is allowing an integration to quickly and temporarily revert our API to the deprecated behavior if it breaks, but this is not possible for this migration.

We’ve added some temporary features to our API for integrations to be ready and empowered to handle the transition, but integrations must be built to use them if they are to handle the transition well. Read our API team’s forum post for further details.

5 Likes
3

Hi @Matt_Bramlage!

I also found that in terms of the string-IDs change, this thread has some really useful info from you guys, especially as it relates to upcoming webhook changes:

3 Likes
4

Thanks for the details. What about projects that are created with the API? Does the format you need to use depends on the migration status of the organization? Sorry if my question does not make sense :thinking::sweat_smile:

5

As workspaces and organizations are migrated, new projects created in those workspaces will automatically use the new data model, i.e., we will ignore the layout field in the request to create a project and will always create a board-style project.

6

as for most requested features, I hope one of them is the ability to “collapse history” in a note/todo. seeing endless “xx changed the due date…” lines makes for a very messy card.

7

I understand I think you’re saying “board-style” in terms of the data model, but how will we convey what the initial UI view should be for a new project? It’ll be really important for integrations like Flowsana that it creates new projects displayed initially in a List view.

8

We don’t support setting the “view” of a project through the API, but now that we have four different views (list, board, calendar, and timeline) we’re considering exposing that option. We’ll post more about that when we have new information.

For migrated workspaces, although the data model will be boards-style, the default view should still be “list.”

9

That would be fantastic, Joe!

Excellent! How about new projects created via the API? Also still “list”? :crossed_fingers:

10

Yep, sorry, I wasn’t clear there—I was specifically referring to API behavior. In the web app, the project creation flow is changing to accommodate the new data model and there may not be a default (i.e., users might have to choose the default view when creating the project).

1 Like
11

We use https://forms.asana.plus/ to have our Wufoo forms automatically load into Asana. Will this be effected by this change and do we need to do anything?

12

Hi @Darlene_Steele, integrations and apps built or maintained by Asana will be updated by our internal teams to support the coming API changes.

13

@Joe_Trollo

Hi Joe, thanks for the heads up regarding the API changes. I’ve enabled client.headers[“Asana-Enable”] = “string_ids” in my python application so gids can be used instead of id going forward.

My concern is regarding change #2 Sections data model is changing. I am not clear if this change will affect my application. Currently the only thing my application does is a nightly export of all tasks in my list projects. I am not using sections in my application, but my users do use it via the Asana Web UI. I am currently searching for tasks by the project and storing all the metadata in a list and then iterating through each task in the list. Below is a snippet of my code.
"
tasks = client.tasks.find_by_project(project[‘gid’], {“opt_expand”:“name,
projects, workspace, gid, due_on, created_at, modified_at, completed,
completed_at, assignee, assignee_status, parent, tags, custom_fields”})
"

Will change #2 affect my application in any way?

14

Hi @Jon7, yes, you will be affected by the sections migration. Currently, listing all tasks in a list-view project will include old-style task-sections. After the migration, these tasks-sections will be converted to column-sections and will no longer appear when you fetch all tasks in the project. Also, there will be no more “list projects” once the migration is finished. All projects will be able to be viewed as both a board and a list.

15

Thanks Joe,

Just to be clear, are you saying that my application built via the python API will be affected or how I interact with Asana via the UI? My application exports all tasks (“real tasks”, not “section tasks”) out of my project and does not discriminate based on “task-sections”.

From the " [Sections are dead! Long live sections!]" post you mentioned there are 3 paths I can take regarding this change, and one of them is do nothing because my application actually does not use section to determine task information. Based on what I am reading I don’t think I need to change my code but I wanted some clarity for my use case, which is outlined above.

Thank you so much for the quick response!

16

What @Joe_Trollo is saying is that currently, when you retrieve all tasks from a list-view project, your list of tasks includes any sections which exist in the project - because in the current data model, in list-view projects, sections are merely tasks with a flag on them to indicate that they’re sections. You might not doing anything special with those section-tasks; you might not even realize they’re in there, but they are.

After the migration, when you retrieve all tasks from a project, any sections which exist in the project will no longer be included in the list of objects you get - because they will no longer be tasks (but rather will be their own distinct object type). So in that sense, the migration will change what’s included in what you’re retrieving.

The other thing he points out which will be different is that there will no longer be any distinction of “list-view” vs. “board-view” projects. Every project will be identical in terms of its data model, and will be able to be viewed in either format in the UI. So when you say “a nightly export of all tasks in my list projects”, realize that there won’t be any concept of a “list project”, there will just be “projects”. That might or might not affect which projects you’re exporting, but probably something you want to think about.

4 Likes