[ Upcoming ] Custom fields Team Sharing

English Forum Developers & API Changelog
1

Summary

Note: This is a follow-up similar to Portfolio Team Sharing.

Custom fields 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 custom fields remain a paid feature

  • Impacted:

    • Users utilizing the API to view and manage custom field memberships via the /memberships endpoints:
      • The member field in the custom field membership resource might now represent a team
      • If you compute a list of users with access to a custom field, 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:

    • For specific events like (e.g., custom_field_member_added, custom_field_member_removed, or custom_field_member_access_level_changed), event details may now refer to teams, not just users

Usage

A response can now include team memberships:

{
  "data": {
    "gid": "1",
    "resource_type": "membership",
    "resource_subtype": "custom_field_membership",
    "parent": {
      "gid": "2",
      "resource_type": "custom_field",
      "created_by": {
        "gid": "3",
        "resource_type": "user",
        "name": "User Name"
      },
      "resource_subtype": "text",
      "type": "text",
      "name": "text",
      "is_formula_field": false
    },
    "access_level": "admin",
    "member": {
      "gid": "4",
      "resource_type": "team",
      "name": "Team Name"
    }
  }
}

Migration steps

The response shape isn’t changing - but, any client code that previously assumed a resource_type of user would need to be updated. For example, if the application previously tried to load a user object from the member gid, this would now need a conditional check, based on resource_type.

Timeline

Initial rollout is expected begin by EOW, with a gradual ramp-up over the next week.

Usage

No new endpoints are being introduced. The following is an example 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 custom field",
        "resource_type": "custom_field"
      },
      "resource_type": "membership",
      "resource_subtype": "custom_field_membership"
    },
    {
      "gid": "121314",
      "member": {
        "gid": "151617",
        "name": "Product Marketing",
        "resource_type": "team"
      },
      "access_level": "admin",
      "parent": {
        "gid": "1234",
        "name": "Marketing custom field",
        "resource_type": "custom_field"
      },
      "resource_type": "membership",
      "resource_subtype": "custom_field_membership"
    }
  ]
}

Migration steps

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

Resources

5 Likes
2

@Andrew-asana Cool! @Forum-team I think this means Add team to custom field access can be marked as in-development :slight_smile:

3 Likes