Use cases
Background
Alice is a researcher at a lab and she is in the process of starting a new project. She is trying to recruit people to join her research team to work on her new project. Alice thinks that her friend Bob who is a researcher at a different lab might be interested in joining her team.
Use case A - Alice wants to invite Bob to join her Synapse team.
| Goal | Alice wants to invite Bob to join her Synapse team. |
| Primary actor | Alice |
| Secondary actor | Bob |
| Precondition | Alice has created a team and she is at her team's page. |
| Postcondition | Bob receives an email invitation to join Alice's team. |
Workflow
Main success scenario | Step 1. Alice invites Bob to join her team by entering his email address and an optional invitation message. Step 2. System sends Bob an email containing an invitation link to join Alice's team. |
| Error scenarios | Replacing step 2.
|
Mockups
Use case B - Alice wants to invalidate the invitation she sent previously.
| Goal | Alice wants to invalidate the invitation she sent previously. |
| Primary actor | Alice |
| Secondary actor | Bob |
| Preconditions |
|
| Postcondition | The invitation link Bob received is no longer valid. |
Workflow
Main success scenario | Step 1. Alice retrieves the pending invitations to her team and removes the one associated with Bob. Step 2. System invalidates the invitation link sent to Bob. |
Mockups
Use case C - Bob wants to create a Synapse account and accept Alice's invitation.
| Goal | Bob wants to create a Synapse account and accept Alice's invitation. |
Primary actor | Bob |
| Secondary actor | Alice |
| Preconditions |
|
| Postcondition | Bob is part of Alice's team. |
Workflow
Main success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob creates his new Synapse account. Step 4. The web client displays Alice's invitation to Bob. Step 5. Bob accepts Alice's team invitation. Step 6. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
Use case D - Bob wants to sign in to his existing Synapse account and accept Alice's invitation.
| Goal | Bob wants to sign in to his existing Synapse account and accept Alice's invitation. |
Primary actor | Bob |
| Secondary actor | Alice |
| Preconditions |
|
| Postcondition | Bob is part of Alice's team. |
Workflow
Main success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob signs in with his existing Synapse account. Step 4. The web client displays Alice's invitation to Bob. Step 5. Bob accepts Alice's team invitation. Step 6. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
Use case E - Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation yet.
| Goal | Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation |
Primary actor | Bob |
| Secondary actor | Alice |
| Precondition |
|
| Postcondition | Bob has a Synapse account with a pending invitation to join Alice's team. |
Workflow
Main success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob creates his new Synapse account. Step 4. The web client displays Alice's invitation to Bob. |
Mockups
Flow Diagram
Discussion about the rationale behind some design decisions
We always want to allow Bob to choose the account he joins Alice's team with. This led to the following design decisions:
- In earlier versions of the design, if the email entered by Alice was already associated with an existing Synapse account, a membership invitation to that account would be created instead of sending an email invitation. The current design changes this behavior and instead, the system always sends an email invitation to Bob and the membership invitation to the Synapse account isn't created.
- Even if Bob is already signed in to Synapse in his browser, clicking on the invitation link should always ask Bob to sign in again. This avoids the case where Bob accidentally joins the team with the account with which he is currently signed in.
Bob should not be automatically added to the team after registering a new account / signing in to his account, but instead he should need to manually accept the membership invitation. This separates the process of registering for a Synapse account and joining the team, giving Bob the chance to explore Synapse without committing to join Alice's team.
Proposal
Use cases to support
I propose to support all the use cases except use case B. After multiple discussions about the necessity of use case B, I have come to the conclusion that it's an edge case that would incur significant development cost for little benefit. Supporting it would require our system to keep track of the invitation sent by Alice in some form, which is a requirement that none of the other use cases impose on us.
Models to implement
| EmailInvitation | MembershipInvtnSignedToken |
|---|---|
emailAddress teamId | emailAddress inviteeId inviterId teamId hmac |
Related models: AccountSetupInfo, MembershipInvtnSubmission
Services to implement
| Action | Intended User | URI | Method | Request Parameters | Request Body | Response Body | Success Response Code | Notification Sent to | Notes |
|---|---|---|---|---|---|---|---|---|---|
| Send email invitation with link to join a team | authorized user | /emailInvitation | POST | EmailInvitation | 200 OK | Email address provided | The invitation link will contain an encoded MembershipInvtnSignedToken with inviteeId set to null | ||
| Create MembershipInvitation using a signed token | public | /tokenMembershipInvitation | POST | MembershipInvtnSignedToken | MembershipInvtnSubmission | 201 Created | Similar to POST /membershipInvitation, but using a signed token for authorization. Also, doesn't send any email notifications. |
Related services: POST /principal/available, POST /account, POST /session, POST /membershipInvitation
Example implementation with Synapse web client
As the use cases above, the inviter is Alice and the invitee is Bob.
- Alice invites Bob to her team by entering his email address.
- Web client constructs an EmailInvitation using Bob's email address and Alice's team's id, then uses it to send a POST /emailInvitation request to the backend.
- Backend constructs a signed MembershipInvtnSignedToken with Bob's email address, Alice's team's id, Alice's id and a null inviteeId (because we don't know Bob's account's id yet).
- Backend serializes the MembershipInvtnSignedToken, embeds it into an invitation link to the web client and sends the link to Bob's email address.
- Bob clicks on the link and does one of the following:
- Registers a new Synapse account. [1]
- Web client checks that Bob's email address is a valid account alias through POST /principal/available.
- Web client constructs an AccountSetupInfo [2], then uses it to create Bob's account through POST /account and receives a session token.
- Signs in to his existing Synapse account.
- Web client retrieves a session token through POST /session.
- Registers a new Synapse account. [1]
- Web client deserializes and validates the MembershipInvtnSignedToken in the link, then sets the inviteeId to the id of the account Bob used (extracted from the session token).
- Web client re-signs the MembershipInvtnSignedToken, then uses it to send a POST /tokenMembershipInvitation request to the backend.
- Backend validates the MembershipInvtnSignedToken and uses it to create a MembershipInvitation from Alice's team to Bob's account.
- Web client receives backend's 201 response, then directs Bob to his profile's Team tab, where he has a pending MembershipInvitation to Alice's team
- Bob accepts Alice's invitation (using the existing MembershipInvitation services).
[1] Note that this process is a bit different from the normal registration workflow because we are avoiding to have to validate Bob's email address. It'd be nonsensical to ask Bob to validate his email address because he reached this state by clicking a link sent to that very email address. Also note that this workflow only allows Bob to register the email address to which the invitation link was sent.
[2] Note that the web client needs to construct a valid emailValidationToken, making up a timestamp in the process.