[Change] Upcoming changes to stories

English Forum Developers & API Changelog
, , ,
1

Summary

We’re making a change to member_added stories. These stories are created when a user (and soon teams!) is added to a project and show up as notifications in the Inbox page.

Once teams are allowed as members of projects (more information here), the member of a story could be either a user or a team as a resource_type.

Who is affected

You might be interested in these changes if your application reads stories. For example:

  • Fetching all stories that have a project as a parent
  • Fetching a particular story by id

This could be a breaking change if your app:

  • Assumes the member.resource_type field is always set to user
  • Uses the project members field to get a complete view of project membership

The project members field will not be updated to return teams as members. Once team sharing is implemented, the project members field will be incomplete and as it won’t provide an accurate representation of who the members are for a project. This change will render the members field essentially deprecated and it will be marked as such in the developer docs.

Changes

This change impacts member_added stories for projects (resource_subtype: “member_added”). These stories have an optional member.resource_type field which previously could only be user. Going forward, member.resource_type could be either user or team. See examples below.

Affected endpoints include:

  • GET /projects/:project_gid/stories
  • GET /stories
  • GET /stories/:story_gid

Note: Some of these endpoints are not documented, though our logging shows they are used by some apps. We plan to document them in the near future.

Examples

GET /stories/160130?opt_fields=resource_subtype,subtype,member

{
        "gid": "160130",
        "member": {
            "gid": "75604",
            "resource_type": "user"
        },
        "resource_subtype": "member_added",
        "subtype": "project_member_added"
}

GET /stories/160435?opt_fields=resource_subtype,subtype,member,member.name

{
        "gid": "160435",
        "member": {
            "gid": "75631",
            "resource_type": "team",
            "name": "Marketing"
        },
        "resource_subtype": "member_added",
        "subtype": "project_member_added"
}

Timeline

Currently

  • Only users can be added to projects.

May 1st – Early Access

  • Gradual rollout of teams memberships begins for specific workspaces which have requested it

July 15th – General Access

  • Team memberships are available for all Asana customers

Questions & Feedback

Let us know if you have any questions or concerns about how this change may affect your app.

Best,
Asana DevRel

4 Likes
2

An insightful developer question has brought it to our attention that this could be a breaking change for apps that rely on stories generated by the project members field. I have updated the above post to include a warning about this field:

This could be a breaking change if your app:

  • Assumes the member.resource_type field is always set to user
  • Uses the project members field to get a complete view of project membership

The project members field will not be updated to return teams as members. Once team sharing is implemented, the project members field will be incomplete and as it won’t provide an accurate representation of who the members are for a project. This change will render the members field essentially deprecated and it will be marked as such in the developer docs.

2 Likes