Mentioning a Team in a Discussion Thread
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
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:
Look up principals (User and/or Team) base on a prefix.
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
- PLFM-3875 - Getting issue details... STATUS
- PLFM-4202 - Getting issue details... STATUS
- PLFM-3458 - Getting issue details... STATUS
- PLFM-3829 - Getting issue details... STATUS
- PLFM-3659 - Getting issue details... STATUS
Comments
Comment from @Kimyen Truong – there are some messages that fit in (3) but are using the infrastructure for (2) above; we should fix this.
@Meredith Slota (Unlicensed), what do you think about making your comment an actual design docs? I found myself reference to this every single time the Synapse notification topic comes up.
I recommend classifying these messages into categories so that we can deal with categories as a whole rather than each individual message. I'm explicitly NOT including the method of sending here since these can originate in multiple ways, but more thinking about "classes" of things. Here's what I'm thinking (open to alternate ideas):
Mission-critical Synapse-to-person notifications: these are notifications that the Synapse system sends that MUST go through to the user, in order to create/update their account. This includes messages like: New Account Email Validation, Additional Email Validation, Welcome to Synapse, and Password Reset.
Opt-out? Globally, no. But we should keep these to a minimum if possible. Decision: NO, no opt-out.
Prompt user to take requested action next time they visit Synapse? Decision: We don't do this yet (except for Password Reset which is in real-time and they need to go to their email to fix) we may revisit this later, but no action now.
Person-to-person (or person-to-team) direct messaging: these are messages sent directly from one person-user to another individual or group of person-users, with intent. This includes messages like: Someone sent me a message, and Someone sent my team a message. USES the <name>@synapse.org email-surrogate.
Opt-out of person-to-person emails? Decision: Yes, the communication happening outside of Synapse, e.g. via an email client sending a direct message to user@synapse.org.
Note: users may be attempting to opt-out of specific user communication (akin to blocking them) rather than all users, we won't tackle this now.
Opt-outs of person-to-team emails? E.g. Currently team managers opt-out their teams; we will change that to add ability for individuals to opt-out of team messages (or "all my teams" only?). Decision: Ok to opt out of emails sent to my teams, we should assume that people will ultimately want to manage these emails by specific teams rather than "all teams" for reasons.
Kept these in exposed inbox/outbox? Thus users can still find if unsubscribed from these emails. Decision: Not currently prioritized but agree with principle.
Less-mission-critical Synapse-to-person notifications: these are system events that Synapse wants to notify and/or email someone about, with varying levels of importance, but explicitly not mission-critical. These include notifications around submissions, events in discussion forums user has subscribed to, and requests for different things (join team requests, access requests, etc.). One critical assumption for these is that the user should still be able to see (in some way) a notification in the Synapse platform if they choose not to receive emails about these, so that the information is not lost.
Note: I don't think we require that all notifications be exposed NOW, just that this should be the general principle going forward; notifications of this type should be "findable" in the platform, not just in email. This adds value to the platform as well and helps users understand what's happening.
Users can already see on team tabs invitations, and new discussion threads float to the top.
Decision: We will add granular opt-on for receiving emails for user mentions and for receiving emails when a team a user is IN is mentioned, but not (yet) specific forums or threads w/in forums or specific users initiating mention. This does leave options for abuse or overuse; we will explore tackling this in another way for now.
Note: users may be attempting to opt-out of specific user communication (akin to blocking them) rather than all users, we won't tackle this now. This is similar to messaging.