performant-software / Annotation-Studio

An online annotation platform for teaching and learning in the humanities.
http://www.annotationstudio.org
GNU General Public License v2.0
5 stars 1 forks source link

User invitation system with CSV imports #409

Closed camdendotlol closed 2 years ago

camdendotlol commented 2 years ago

What this PR does

This PR adds a CSV-based invitation system to COVE.

At /anthologies/[title]?tab=users, admins and teachers can invite students to an anthology by uploading a CSV file in the following format:

email,firstname,lastname
first@example.com,First,User
second@example.com,Second,User

The invite flow is pretty simple:

https://user-images.githubusercontent.com/64725469/168316006-fdd14276-babe-4d7e-a8ba-846238644ac8.mov

When ingesting new users, we call the invite! method from the devise_invitable gem, which is basically the same as Rails's create! method but it handles invitation fields too. I passed a param to skip sending the email right away, because it takes a couple seconds for each one to send. Instead, the controller puts the email jobs in a queue that runs in the background. The result is that, even for a few dozen users, there is minimal loading time for the ingestion process.

This PR adds a new column to the users table in the anthology settings to indicate whether a user has accepted their invitation: Screen Shot 2022-05-13 at 11 27 36 AM

I also added handling for each of the three types of authentication: email/password, OAuth, and SAML. The view for accepting an invite will display different options depending on which methods the tenant has enabled. For email/password authentication, we use devise_invitable's default form that allows the user to set their password and other details. For OAuth and SAML, the view displays simple login buttons that take the user to their institution's login page. The OAuth and SAML buttons are functionally the same as the existing ones in the navbar, and I've added a few lines to the authentication controller to check for a pending invite and accept it when users sign in with those methods.

How to test

This needs to be tested on multiple tenants with a range of the three types of authentication. This may be challenging, especially for SAML, which would require a tenant or two to cooperate with us on setting up a staging site.

For email and OAuth testing, the standard staging server at https://staging.covecollective.org/ should be usable. OAuth is provided by https://navsa.org.

Here is an example CSV file to use for invites: https://pastebin.com/raw/HwmKDeaD

  1. Go to /anthologies and create an anthology with whatever title you want.
  2. Click on the Users tab to get a list of users (it will start off empty)
  3. Click the CSV invite button and upload the file.
  4. The page should refresh within a few seconds and you should see the new users listed, with "Pending" in the Invitation column for all of them. Consider it a bug if the page takes an exceptionally long time to load.
  5. You should receive emails for each new user in your inbox over the span of the next few minutes.
  6. Open an incognito tab in your browser and paste one of the invite links from the emails.
  7. Log in with whatever method the tenant uses.
  8. Once you've signed in as the new user, you should be redirected to the new user's dashboard with your anthology listed on the screen.
  9. Go back to your non-incognito browser window, with the list of anthology users, and refresh the page. The user for whom you accepted the invite should have "Accepted" in green text for the Invitation column.
camdendotlol commented 2 years ago

@SteveMarvin Here are some instructions for SAML testing:

The two sites to test are https://purdue-staging.covecollective.org and https://princeton-staging.covecollective.org.

Complete the steps from above, but this time use the okta.com login option for all users.

Also, when you receive the invite links in your email, make sure they link to the correct tenant. For example, if you invite users on purdue-staging.covecollective.org, the email sent to those users should direct them to purdue-staging.covecollective.org and not to some other domain.