Educator Signup Flow

Introduction

The educator sign up flow is generally divided into four steps (Sign up, Verify your email, Request faculty verification, Complete your profile), but it interacts with a couple external 3rd party APIs in the background (SheerID and Salesforce). Exactly how and at which point we interact with those APIs is the trickiest part of Accounts for the educator signup flow.

In order to develop a clear understanding of all the parts, I find it better to explain the flow from the different perspectives.

From the frontend perspective

Step 1

User types in this information:

• First name
• Last name
• Phone number
• Email
• Password
• User checks these checkboxes:
• Receive newsletter? (optional)
• Agree to the Terms of Use and Privacy Policy

What happens in the backend:

• A user account gets created. The user's state is set to "unverified" because the user has not yet verified their email address. (Note that until the user verifies/claims that email address as theirs, anyone can subsequently come in and complete the signup form with the same email address, including themselves at a later time).
• An email gets sent. The email includes a pin that the user can enter in step 2 of the signup flow. And it also includes a link that the user can click on, which has the same effect as entering the PIN in step 2.

What happens in Salesforce:

• Nothing. Nothing gets sent to Salesforce yet because the user has not yet verified their email address. It could have been a bot that submitted the signup form or a fake or malicious user which we don't care about storing in Salesforce.

Step 2

User types in this information:

• PIN

OR, the user can click in the link sent in the email as part of step 1.

What happens in the backend:

• The user's email gets verified. This means that no one else can sign up with that same email address and no else can add it to their account.
• The user's account gets activated. The user's state changes to activated and a new salesforce lead with the user's information gets created.

What happens in Salesforce:

• A new lead shows up. The lead is not yet "finalized" though (FV_Final__c is false), which means that we are still waiting for Accounts to gather the rest of the user's information as the user completes the rest of the steps (3 and 4). Since we don’t know the user’s school yet, Accounts sends “unknown to Accounts” as the school name (because a school name is required by Salesforce, otherwise a Lead cannot be created), the verification status is set to pending_faculty, and the role is “instructor”.

Step 3

The user is presented with a screen that comes from SheerID. We call this the SheerID iframe.

The user has the opportunity to type in this information:

• Country
• School name
• First name
• Last name
• Email address (this field is present but not editable by the user)

But do note that the first name, last name, and email address are pre-populated using what information the user previously provided us with in step 1. However, the email address is not editable, and if they edit their first or last name, it will be updated in the background until SheerID posts a web request with that information which, typically, is immediate and happens successfully, but if there is an error, then it could potentially result in data loss; we would never get that user's information.

The most important piece of information that users have the opportunity to enter in this screen is their school’s name. The school name must correspond to the school that provided their email address.

What happens in the backend:

• In the ideal scenario, the user gets instantly verified by SheerID.
• SheerID sends us the user’s Verification ID in a web request to Accounts.
• Using the SheerID Verification ID, we make an API request to gather the user's verification status and their school's official name according to SheerID. If the user updated their first name and/or last name, then we also update those fields in Accounts because we trust SheerID. Then we update the user’s Salesforce Lead with the new and the updated information. The user’s account is not yet “finalized” though, even if they are verified by SheerID, mainly because we do not yet know the books (aka. “subjects”) that they have adopted or are interested in adopting until step 4.

However, in the scenario that the user resides in a different country which is not supported by SheerID (and therefore is not an option in the Country dropdown), then the user will click on a link underneath the Country field which sends them to step 4, effectively skipping step 3.

Or, in the scenario that the user is a homeschool educator and therefore cannot find their school (because SheerID does not support homeschools), then the user will click on a link underneath the School name field which sends them to step 4, effectively skipping step 3.

What happens in Salesforce:

• In the ideal scenario, the user's Lead gets updated. The Lead's FV_Status__c ("Faculty Verification Status") is set to confirmed_faculty and the Company (school) name is set to what SheerID reports to us as the user's school name. Also, potentially, the user's first and last name gets updated.

In the less-than-ideal scenarios, no updates will be made to Salesforce yet, but the user will need to be manually verified by our Customer Service team after completing step 4, so the user's needs_cs_review attribute (Needs_CS_Review__c field in salesforce) will be set to true.

Step 4

The final step is to get the pieces of information that Salesforce needs from the user in order to build a Contact, most importantly, the books they are using or the ones they are interested in using.

The user has the opportunity to give us this information:

• Which of the following best describes your role?
• How are textbooks chosen at your institution?
• How are you using OpenStax?
• How are you using OpenStax?
• Total number of students you teach per semester
• Books you've used in your courses

However, not all of those fields will show up for the user every time; it depends on what the user selects for the previous field. For example, if the user selects "Other" as their role for the first question, then the only field they will see is "Role name" which they can type in.

What happens in the backend:

• Accounts makes another update to the salesforce lead for the user with the new information, and the user is then “finalized”.

What happens in Salesforce:

• The salesforce automation should now create a Contact for the Lead — using information from the Lead. If the lead's faculty status was set to Approved, then the Contact should be set to approved_faculty.

From the Salesforce perspective

Step 1

Nothing is sent to Salesforce yet.

Step 2

Once the user verifies their email address, then Accounts sends all the information we have from step 1. Namely:

• FirstName (the user's first name, required in step 1)
• LastName (the user's last name, required in step 1)
• Phone (the user's phone number, required in step 1)
• Email (the user's email address, required in step 1)
• LeadSource (always set to OSC Faculty)
• Application_Source__c (most often set to Accounts unless the user is a Tutor user, in which case it would be Tutor Signup)
• Role__c (most often set to Instructor, or it could be Administrator, or Other)
• OS_Accounts_ID__c (the user's autogenerated ID in Accounts — user.id)
• accounts_uuid_c__c (the user's autogenerated UUID in Accounts — user.uuid)
• Company (the user's school name, ie. "Rice University (Houston, TX)")
• FV_Status__c (initially pending_faculty and then changes to either confirmed_faculty or rejected_faculty)
• FV_Final__c (initially false and then true once the user completes step 3 AND 4)
• Needs_CS_Review__c (false unless the user was rejected by SheerID and/or completes the form for manual Customer Service review)
• Newsletter__c (false unless the user checked the checkbox in step 1 to receive the newsletter)
• Newsletter_Opt_In__c (false unless the user checked the checkbox in step 1 to receive the newsletter)

Step 3

In addition to everything sent in step 1, this information is sent to Salesforce when the user is approved/verified by SheerID:

• The user's Company (aka. school)
• The user's FV_Status__c as confirmed_faculty
• The user's FirstName IF the user typed in something different in step 3 than what they entered in step 1.
• The user's LastName IF the user typed in something different in step 3 than what they entered in step 1.

But if the user was rejected, in addition to everything sent in step 1, this information is sent to Salesforce:

• The user's FV_Status__c as rejected_faculty

Step 4

In addition to everything already sent in previous steps, this information is sent to Salesforce:

• Role__c
• who_chooses_books__c
• Adoption_Status__c
• Subject__c
• Number_of_Students__c
• OR only the Role__c along with other_role_name__c IF the user selected "Other" as their role

From the SheerID perspective

All of the interactions with SheerID happen as a background process in Accounts, unbeknown to users.

Step 1

N/A

Step 2

N/A

Step 3

SheerID receives this information from Accounts about a user:

• First name
• Last name
• School name
• School-issued email address

SheerID in turn responds to Accounts with this information:

• SheerID verificationId

Subsequently, Accounts makes an API request to SheerID with the verificationId, in which case SheerID responds back with this information about a user:

• First name
• Last name
• School name
• Email address
• Current step (which can be success for approved, rejected for rejected, or docUpload for when the user goes into the document upload step which gives the user an opportunity to provide documents that prove that they are actually a faculty member of the school that they claim they are)

Step 4

N/A

---

FAQ

1. If a user stops at steps 3 or 4, how do they get back to steps 3 or 4?

The next time they log in they will be redirected, or… also when they try to visit their profile. But most importantly, by design, in os-web at least, they should see a link in the top-right dropdown that says “Finish signing up”.

Doc with images

https://docs.google.com/document/d/e/2PACX-1vQhyvp1KkazqWBnL6Qh1OY2AIpSksMj5UkvtpAPG-Ybvkwvnb1QJd99cJIQaldOcT8hnAi-8yRVzs2L/pub