[Halted] Upcoming changes that impact getting and setting memberships and access levels

Hi folks,

We have an updated timeline for these changes:

Date Phase
2023-02-06 Opt-In available
2023-03-10 Opt-Out available
2023-04-19 Generally Available (opt-out no longer available)
3 Likes

Hi @sasha_f !

Couple of things:

This should be “add, remove, or query members from any resource”, yeah?

Can you elaborate on what “effective_access_level” means here? Thanks!

:white_check_mark:

Users have a standard_access_level for Projects, Portfolio, and Goals via
their direct membership. At the moment in the API, we’ve exposed this standard_access_level as write_access and other properties – this is part of what will also be changing once we update the docs and schema.

However, users may be on a team that has a different standard_access_level
than their direct membership. When there is a difference, the highest access
level across all memberships (if a user is on several teams with access),
becomes the effective_access_level. This effective_access_level is then used
to determine the user’s tier of access.

That said, we actually have modified the spec for this feature for the first
iteration to remove the GET /memberships/effective_access_level/* routes. We
expect to add it back the feature as a property on membership objects instead of its own
endpoint to improve the ergonomics for API users.

I’ll update the original post with these details and your first comment!

2 Likes

@Phil_Seeman I need your help navigating the updates: does this mean we can now programatically put someone as comment-only on a project?

1 Like

My instinct here is no, but I’m actually not sure and will find this out for you! It might be mid-next week that I get the answer tho.

1 Like

ok, so it turns out yes, with this change you can set someone as comment-only. Here’s how you’d do it:

{
  "member": "<User or Team resource>",
  "parent": "<membership-capable resource>",
  "resource_type": "membership",
  "resource_subtype": "project_membership",
  "standard_access_level": "commenter",
  "<subtype-specific fields>": "<subtype-specific values>"
}

standard_access_level for project_membership will include the following values:

  • editor
  • contributor
  • commenter
4 Likes

Excellent, thanks so much!

@sasha_f

Does it mean we can’t test it before February 6th, when we’ll have to optin?

The code you shared, can I use it to do a PUT on memberships/XX_GID_XX and simply passing { "standard_access_level": "COMMENTER" }?

Thanks

If the user is already a member of that sources, it would be the PUT form. If the user is not a member, you’d use the POST form and then be issued a membership gid in the response.

And yes, until this becomes available as opt-in, you won’t be able to test it. I will comment on this thread once it becomes available (which we’re anticipating is tomorrow).

2 Likes

Hi @sasha_f,

I have a few questions:

  1. When the resource is a team, can it have a team as a member? (If yes, then can that be the same team as the resource? I would assume no.)

  2. In the first prototype you show where the resource can contain users or teams, how does one know whether a given member is a user or a team?

  3. To make sure I’m clear: standard_access_level will be returned, and can be set, when this changeset is in effect. However, effective_access_level will not initially be available to get or set.

  4. If I’m right on #3, then this would seem to mean that while one will receive a standard_access_level for a member, it might not be the access level that’s actually in effect for that member (if they have a higher effective_access_level that we won’t be able to see). Similarly, one can set standard_access_level, as in your example of setting a comment-only user, but that action might not actually have any effect if the user has an effective_access_level that’s higher than the one that’s being attempted to be set (and after making the call to set the standard_access_level, we’ll have no way of knowing whether it actually worked or not).

1 Like

@sasha_f is this out yet :slight_smile: ? thanks

1 Like

Hey folks, this is now available as Opt-In, and with the /memberships endpoint available for everyone.

No, teams cannot have other teams as members.

The member field will point to a team or user resource, which will have a resource_type field, like so:

{
  "member": {
      "gid": "123",
      "resource_type": "user",
  },
  "parent": "<membership-capable resource>",
  "resource_type": "membership",
  "resource_subtype": "<one of team_membership, project_membership, workspace_membership, portfolio_membership, goal_membership>",
  "<subtype-specific fields>": "<subtype-specific values>"
}

This was confusing in the OP, and I’ll update to include this! Thanks for the keen eye and great question!

Correct, as of now, the following are true:

  • only standard_access_level is available
  • effective_access_level is not available
  • it’s possible that the “effective access level” (which will be available in the future as effective_access_level) that’s in effect for a member may be greater than their standard_access_level
    • it is not possible to identify the above state via the API.

In the future, once effective_access_level becomes available, that state will be identifiable.

2 Likes

Hi @sasha_f , thanks for the updates—excited to test-drive it this week!

One question, and sorry if I’ve missed this context somewhere further up in this thread. Is there a way to explicitly turn off notifications via these new endpoints? Eg, in this screenshot I would assume the standard_access_level options you outlined (below) map to the Can edit and Can comment options in the GUI.

Do those values somehow also map to notification preferences (the second highlighted bit in that GUI screenshot)? Or is there another way to set/disable notifications via this endpoint?

Thanks again!

Looking into this for you! My gut says this is not available via the API at this time.

Okay, thanks for checking! Also, when trying to create a new Project Membership, I’m getting:

"message": "Please include a valid standard_access_level: ADMIN CONTRIBUTOR COMMENTER",

Tried sending both the documented write_all and the prompted CONTRIBUTOR values in upper/lower case. Do we (can we, if so?) need to opt in to this API update, to have access to these endpoints? That endpoint does work when we remove the standard_access_level altogether.

Also getting this, when attempting to hit the DELETE endpoint for memberships:

"message": "No matching route for request"

which endpoint are you using? Are you setting any Asana-Enable headers?

which endpoint are you using? Are you setting any Asana-Enable headers?

POST’ing to https://app.asana.com/api/1.0/memberships - but wondering if I’ve got an invalid header. What should that Asana-Enable be set to for this?

To avoid potential confusion (“I set them as comment-only via the API but they can still edit stuff!”), I’d recommend that you document this as a note in the API docs.

1 Like

Is GET /workspaces affected too?
We got the error about this change in response, but this endpoint is not mentioned here

@sasha_f