[Change] Project team sharing is coming!

Hello! As we continue to adjust our project permissions model to better support sharing at scale, we want to give the developer community early notice about what changes to expect over the next year.

After the changes, Asana (and the API) will be able to support sharing that can scale down to projects that are private to a single member and scale up to projects that are accessible to an entire organization, with different groups of people that have different levels of access to that project. We’re enabling this with three user-facing changes:

  1. new project sharing options - share a project with your entire organization (just launched!)
  2. project team sharing - share projects with entire teams! (and not just users)
  3. teamless projects - projects are no longer contained within a team

This update is focused on the project team sharing API changes we’re making. We’ve included the changes below along with an estimated timeline. We’ll keep this estimate up-to-date on a monthly basis going forward.

Preview of upcoming project team sharing changes

When we roll out project team sharing for a workspace, the following changes will take effect:

View and modify team memberships over the API

Our new /membership endpoints will allow you to fetch, create, or modify a team membership for a given project. Lists of project members will include teams and users.

Existing endpoints for adding and removing users to a project will be marked deprecated and no longer preferred. They will not be updated to allow adding team members to a project. However, they will not be removed as part of this release.

GET /memberships?parent={project_gid}

{
    "data": [
        {
            "gid": "11111",
            "member": {
                "gid": "22222",
                "name": "Melissa",
                "resource_type": "user"
            },
            "access_level": "admin",
            "resource_type": "membership",
            "resource_subtype": "project_membership"
        },
        {
            "gid": "33333",
            "member": {
                "gid": "44444",
                "name": "Marketing Team",
                "resource_type": "team"
            },
            "access_level": "editor",
            "resource_type": "membership",
            "resource_subtype": "project_membership"
        }
    ]
}

Team information on project membership audit log events

project_member_added, project_member_removed, and project_member_access_level_changed audit log events related to project memberships may now include team information.

For example, the project_member_added event:

{
    "data": [
        {
            "gid": "12345",
            "created_at": "2024-01-01T00:00:00.000Z",
            "event_type": "project_member_added",
            "event_category": "access_control",
            "actor": {
                "actor_type": "user",
                "gid": "11111",
                "name": "Greg Sanchez",
                "email": "gregsanchez@example.com"
            },
            "resource": {
                "resource_type": "project",
                "gid": "22222",
                "name": "API Documentation Project"
            },
            "details": {
                "added_resource": {
                    "resource_type": "team",
                    "gid": "33333",
                    "name": "Developer Relations Team"
                }
            },
            "context": {
                "context_type": "web",
                "client_ip_address": "1.1.1.1",
                "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
            }
        }
    ]
}

Special cases for projects in a private team

A project’s team field may be null when the team is private to you

A user might be added to a private project, but not the private team which contains the project. In this scenario, the team field on the project object may appear to be null.

In the next and final phase of project permissions enhancements, projects will no longer have an associated team and the team field will be deprecated completely. We’ll share more about that transition in the coming months.

Project duplication behavior change

The duplicate project endpoint will return an error if you try to duplicate a project in a team that is private to you. This is to prevent users from creating projects for private teams they are not a member of. To mitigate this, you can specify the gid of a team the user has access to in the team field of the request. (If you don’t specify a team, Asana will attempt to create the new project in the same team as the original project.)

POST /projects/{project_gid}/duplicate

{
    "data": {
        "name": "Duplicate project",
        "team": "12345" // team gid the user has access to
    }
}

The private_to_team project privacy setting will be removed

As we shared with the announcement of project privacy settings, the private_to_team privacy setting will be removed as we roll out project team sharing. You will still be able to create a project with privacy_setting set to private_to_team, but instead we suggest that you create it with privacy_setting set to private and add the team to the project.

Create a private project:

POST /projects/

{
    "data": {
            …
            “privacy_setting”: “private”,
            …
    }
}

Then explicitly share the project with the team and assign an access level:

POST /memberships/

{
    "data": {
        "member": "12345", // team gid
        "parent": "98765", // project gid
        "access_level": "editor"
    }
}

Project stories and project membership events / webhooks for team sharing

  • The member_added project story may now include teams as members. More information about this here.
  • Webhooks / events for project memberships - When you add a member to a project it generates a project membership added / removed event. The formats of these events shouldn’t change, but events will also be generated when a team is added or removed from a project.

Timeline of changes

May 2024-July 2024:

Project Team Sharing begins rolling out along with these changes (details above)

  • View and modify team memberships over the API
  • Team information on project membership audit log events
  • Special cases for projects in a private team (null team field and duplicate project behavior change)
  • The private_to_team project privacy setting will be removed
  • Project stories and project membership events / webhooks for team sharing

Later in 2024:

We will stop requiring a team on project creation. More to come here including more specific timeline!

FAQ

How will I know whether or not a workspace is part of the team sharing rollout?

We will return a 400 status code with the following body:

{
    "errors": [
        {
            "message": "Team Project Memberships are currently not supported.",
            "help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
        }
    ]
}

What happens when a user’s individual permissions conflict with their team permissions?
If there is a conflict between a user’s explicit permission and the permission given to them through team membership, the user will be granted the higher access level.

For example, if a user is a viewer on a project, but is part of a team which has the editor access level, they will be given editor permissions to the project.

If you have any additional questions, don’t hesitate to ask! Please subscribe to this thread if you are interested in updates. We may have updates to FAQ and timelines.

Thanks,
John

5 Likes

Amazing; we’ll finally be able to use teams as functional groups!

5 Likes