[Change] Teamless Projects

English Forum Developers & API Changelog
1

Summary

  • As described in [Change] Project team sharing is coming!, projects can now be directly shared with multiple teams!
  • As the latest step in improving the Asana project permissions model, newly created projects will no longer have a containing team and the project.team field will be null.
  • Previously created projects have been migrated so that the containing team is a member of the project.
  • If you currently read the project.team field over the API, you’ll need to update your code to handle a null value for this field and get information from other endpoints. (more details are below)
  • The project.team field can still be written to on create, but can no longer be modified on a project, since the meaning and resulting behavior is ambiguous. (see details below)

Who is affected

  • Anyone using the API to organize projects by their containing team, including:
    • Creating a project with a containing team
    • Accessing all projects with the same containing team

Upcoming changes by endpoint

  • Projects created after this change will no longer have a containing team and the project.team field will be null. The team field will be marked deprecated.
  • For existing projects, the containing team (previously set when the project was created) will be migrated to be a member of the project.
  • To maximize backward compatibility, projects created before this change will continue to return a team gid in the project.team field until that team is no longer a member of the project. At that point, project.team will return null.

All endpoints used to fetch projects, including:
GET /projects/
GET /projects/{project_gid}
GET /workspaces/{workspace_gid}/projects
GET /teams/{team_gid}/projects

  • The team field on newly created projects will be null.
  • Clients that read the team property will be notified of the deprecation via an Asana-Change header.
  • Projects created before this change will continue to have a team set in the project.team field until that team is removed from the project. If the team is removed as a member of the project, the project.team field will become null.
  • All API clients should be prepared to handle a null value for project.team
{
    "data": {
        "name": "Project Name",
        "resource_type": "project",
        "gid": "12345",
        "team": null,      << team can now be null
        "privacy_setting": "public"
    }
}

GET /memberships

  • This endpoint will be updated so that the member filter can be used to fetch all memberships for a team gid.
  • Previously, parent and member were both required, now parent will be optional.
  • If parent is absent, a new resource_subtype must be provided. (project_membership for projects)

GET /teams/{team_gid}/projects

  • This endpoint will be deprecated. GET /memberships should be used instead to get all projects that have been shared with a given team. (see above)
  • To maximize backwards compatibility, this endpoint will continue to function, but will return the projects where the given team is a member (the same as GET /memberships described above).

POST /projects/
POST /teams/{team_gid}/projects
POST /project_templates/{project_template_gid}/instantiateProject

  • The team property will be marked deprecated and no longer required.
  • Setting a team gid on project creation will add that team as a member of the project with the default_access_level but the team field will be set to null.
  • POST /memberships should be used instead to add teams as members to a project.

PUT /projects/{project_gid}

  • You will no longer be able to update the project.team field over the API. The meaning of that update will be ambiguous now that projects are not contained within a team and many teams can be a member of a project. Attempting to update the team will produce an error.

Migration steps by use case

Fetching projects by team

  • Use GET /memberships. Specify the team gid with the member filter along with a resource_subtype of project_membership.
GET /memberships?parent={team_gid}\&resource_subtype=project

Identifying which teams a project “belongs to”

  • Projects no longer belong to a team. Ideally, stop reading and requesting the project.team field.
  • Instead, use the GET /memberships endpoints above and be prepared to handle multiple teams having access to a project, but no longer “owning” or containing the project.
  • If you continue to use project.team, be prepared to catch and handle a null value.

Sharing a project with a team (including on creation)

Timeline

  • In 6 months (roughly April 2025), we expect to begin allowing the creation of projects with no containing team in the Asana website and the API. We will update this post as more precise timelines are available.
    • project.team will be null for a newly created project
    • Previously created projects will continue to return a team gid until that team is removed as a member of the project. At that point, project.team will be null and cannot be reset.
    • You may opt of this change by adding the Asana-Disable: teamless_projects header to your request. Note: projects created in the web application will still have a null value for project.team
  • 2 months after that (June 2025) you will no longer be able to opt-out of this change

Why we’re making this change

  • Asana users will be more free to create projects without caring what team they’re in, and can assign teams as members later.
  • This latest change simplifies the creation of private projects intended to only be shared with their direct members.

Let us know if you have questions or feedback about this planned change. We know changes like this can be disruptive, and we’re doing our best to minimize breakage while continuing to improve and evolve Asana projects.

4 Likes
2

Thanks, @John_Baldo, for the good, clear writeup.

So can we expect somewhere around April that you’ll use the opt-in/out headers (sorry, forgot the proper term you use) when rolling all of this out?

Thanks,

Larry

3

I agree with Larry, @John_Baldo - thanks for this very detailed and clear info!


I think these are all helpful and thoughtful decisions. :+1:


Question:

Will sending the team field cause the PUT call to fail, or it will just ignore anything sent in the team field?

1 Like
4

I think you mean April 2025

Also, how/when will we be able to specify which team(s) get added to a project created from a Project Template? Within the Project Template interface (UI), there is no way to add team(s) to the project that gets created from the template.

2 Likes
5

Hey, I want to quickly acknowledge and thank you for the questions. I am working on getting answers which I will post here and update / edit. And thanks for pointing out the typo, @FreshyJon! Hard to believe 2025 is almost upon us. :sweat_smile:

2 Likes
6

Hi @lpb @Phil_Seeman @FreshyJon ,

Sorry for the slow reply. I’ve updated the post to clarify:

  • We’ll allow an opt-out period (for the API but there still may be a null team value when a project is created in the Asana web app)
  • instatiateProject will have the same behavior as POST /projects and I’ve added it to the list.
  • Attempting to update the team field with a PUT will return an error.
3 Likes
7

Can you help advise how to correct this now to adhere to the change?

image
image802×1408 63.3 KB

image
image802×1408 63.9 KB

9

@John_Baldo or for who is doing a quick text search on ‘duplicate’, how will the team parameter function for:

POST /projects/{project_gid}/duplicate