[ Upcoming ] Portfolio Team Sharing

English Forum Developers & API Changelog
1

Summary

Portfolios in our system will soon support team memberships! This enhancement will allow you to add groups of people (teams) instead of only individual users, making it easier and more efficient to manage access.

Who is affected

  • Not impacted: Users on a free plan, as portfolios remain a paid feature
  • Impacted:

    • Users utilizing the API to view and manage portfolio memberships via the /memberships endpoints:

      • The member field in the portfolio membership resource might now represent a team
      • If you compute a list of users with access to a portfolio, you must now include member teams and use a separate endpoint to retrieve their users, combining them with direct members
      • To determine a user’s access level, compute the effective access by combining direct membership access and team membership access, if applicable

    • Users utilizing the audit log API endpoint:

      • For specific events like (e.g., portfolio_member_added, portfolio_member_removed, or portfolio_member_access_level_changed), event details may now refer to teams, not just users

Timeline

Portfolio Team Sharing is set to begin its rollout in mid-February 2025, with full deployment expected over the following weeks.

Usage

  • No new endpoints are being introduced
  • Sample response from GET /memberships?parent=1234 (note that member objects can now have a resource_type of team in addition to user):
{
  "data": [
    {
      "gid": "5678",
      "member": {
        "gid": "91011",
        "name": "John Doe",
        "resource_type": "user"
      },
      "access_level": "editor",
      "parent": {
        "gid": "1234",
        "name": "Marketing Portfolio",
        "resource_type": "portfolio"
      },
      "resource_type": "membership",
      "resource_subtype": "portfolio_membership"
    },
    {
      "gid": "121314",
      "member": {
        "gid": "151617",
        "name": "Product Marketing",
        "resource_type": "team"
      },
      "access_level": "admin",
      "parent": {
        "gid": "1234",
        "name": "Marketing Portfolio",
        "resource_type": "portfolio"
      },
      "resource_type": "membership",
      "resource_subtype": "portfolio_membership"
    }
  ]
}

Migration steps

  • Ensure any code handling portfolio memberships through /memberships endpoints considers the possibility of team memberships
  • Note that /memberships/{membership_gid} does not currently support portfolio memberships, and support for team memberships is unlikely. Instead, use GET /memberships?parent={portfolio_gid}&member={member_gid} as a workaround

Additionally, when updating your system to accommodate team memberships, it may be beneficial to compute a user’s effective access level by integrating both direct and team memberships. This involves aggregating memberships to ensure that each user receives the highest level of access available through their roles or group associations. Here is a high-level approach to accomplish this:

  1. Retrieve memberships: Obtain all memberships associated with the portfolio.
  2. Identify memberships: From the results, distinguish between direct memberships and team memberships.
  3. Compute effective access level: Combine the user’s direct access level with the access levels granted by any teams

Resources

6 Likes