Document toolboxDocument toolbox

Mentioning a Team in a Discussion Thread

Owned by Kimyen Truong (Unlicensed)
Last updated: Jul 21, 2017
3 min read

Background

At the moment, a user can mention another user in a discussion thread by typing '@username'. A notification email will be sent to the mentioned user if his/her Synapse email is open for Synapse Notification emails. 

Use Case

"For one of the consortia (M2OVE-AD) we have one project with multiple working groups. Each working group has a separate team." Mette, who managing/ providing supports to the consortia via Synapse projects and discussion forum, would like to be able to mention a team (or multiple teams) in a discussion thread so that everyone in the mentioned team are aware of the discussion that relevant to them, and invite them to join the discussion. 

More detailed discussion about the use case are captured in  PLFM-3875 - Getting issue details... STATUS

Requirements

Mentioning a team would work the same way as mentioning a user in a discussion thread including:

  • User type '@team_alias' to start looking for a team they want to mention. 
  • SWC render '@team_alias' with a Team badge.
  • A notification email will be sent to the team.

Required Services

To meet the requirements above, we still need the services to:

  1. Look up principals (User and/or Team) base on a prefix.
  2. Look up principal (User or Team) base on username or team_alias.

Also, teamAlias needs to be exposed, and available in API.

Proposed Solutions for the Missing Services

Option 1 - Add a new service

Revisit Unique User and Team Alias API, and redesign it to meet the current needs.

Option 2 - Modify existing API

  • The web client is currently using GET /userGroupHeaders to look up users or group by name. However, this service doesn't return a unique user and team alias to use in creating markdown. For this option, the proposal is to extend the returned object with the princialAlias.
  • There is an existing service that can be used to look up a principalId given a principalAlias: POST /principal/alias. However, this service requires that the caller provide an AliasType. For this option, the proposal is to make the alias type optional to allow client to search for both user and team given a principalAlias.

Notification Email Potential Issues

Problem 1 - Redundant Emails

In mentioning a user case, if the user who is mentioned already receive an email because of their subscription, the service will not send them a redundant email.
In mentioning a team, if we send the notification email to the team email address, we would encounter a case where some members subscribed to the forum/thread and already receive an email. The system would just send an email to the team regardless of who is in the team. The notification email via team would be redundant to them. 

Problem 2 - Team's SEND_MESSAGE Permission

Each user can change their profile setting to whether or not they would like to receive notification emails from Synapse. By turning their setting off, they won't receive notification email when someone mentioned them in a thread.

Team's SEND_MESSAGE permission is defined in the team's ACL and is separated from its members' profile settings. What would be the appropriate behavior for user A who is a member of team B?

  • Case 1 - User A has Synapse notification email on. Team B only allows team members to send messages to the team.
  • Case 2 - User A has Synapse notification email off. Team B allows anyone to send messages to the team.

Notes

Based on previous discussions, we agreed that:

  • Mentioning a team should use the BroadcastMessageWorker architecture. And BroadcastMessageWorker architecture needs to be refactored to implement this.
  • Allowing a team to opt out of being mention in a forum is a requirement.
  • For other messages, users should have fine grain control on email notification. However, we are not sure if they should be implemented using Subscription architecture. Making a decision on this topic allows us to finalize the scope of the refactor work on Subscription and BroadcastMessageWorker.

Actions:

  • Meredith Slota (Unlicensed) will lead the effort to find out use cases and mockups for fine grain control on email notification. From there, we can decide if it fits in the Subscription architecture. 

Unresolved questions:

  • If user already subscribes to a thread, should they receive the email about their team has been mentioned? What if they are in multiple teams that are mentioned in the same thread?

Related JIRA Tickets