Troubleshooting LMS integrations

Ensure that privacy settings allow student information to be sent to Perusall

When setting up Perusall as an LTI app, make sure that your LMS is sending name, email, and role information to Perusall; Perusall uses this information to assign users the correct role (student or instructor) in the course, show student names in conversations, and send students email notifications when other students respond to their questions or comments. (For example, Canvas has a "Privacy" dropdown that should be set to "Public.")

Ensure that the first launch of Perusall from the LMS is from an instructor account

The first time you click on the Perusall link in your LMS, it should be from an instructor account (not an admin or student account); this will trigger course creation in Perusall. After this point, any member of the course can click the Perusall link and will be taken to the corresponding course in Perusall.

Ensure all required fields are being sent

If LTI launch fails, ensure that your LMS is sending all of these required fields (in particular, some fields will not be sent without the proper privacy settings from above):

  • user_id (an ID number uniquely identifying each user)
  • roles (LTI standard role identifier)
  • lis_person_name_full (full name)
  • lis_person_name_given (first name)
  • lis_person_name_family (last name)
  • lis_person_contact_email_primary (email address)
  • resource_link_title (placement identifier, if gradebook sync enabled)
  • lis_outcome_service_url (URL to post grades back to, if gradebook sync enabled)
  • lis_result_sourcedid (indicator of grade passback location, if gradebook sync enabled)

Ensure Perusall will open in a new tab/window

Make sure that you have selected the option to open Perusall in a new tab or window; otherwise, LTI launch will fail. Perusall blocks LTI launches within an iframe for security reasons.

Ensure that users do not already have Perusall accounts with the same email address

Perusall uses the email address as a unique identifier for each user. If a user already has a Perusall account under the email address on file with the LMS, then LTI launch will fail with the messsage:

There is already an account with the email address [user's email address] so we can't create a new account using the same address.

To resolve this, the user should log in to their existing Perusall account and change the email address in their profile to something different. (To edit a profile, click your name/initials/photo in the upper right corner of the page, and then select "Edit profile.")

Alternatively, Perusall Support can disable an existing Perusall account for users in this situation.

Ensure that the assignment description does not contain newline characters.

Some LMSs fail to properly process LTI launches when the assignment description for an assignment that launches Perusall contains newline characters. Place the description of the assignment on one line.

Ensure that students are launching Perusall assignments from assignment-specific links in your LMS, if you want to use grade sync

In order for the grade sync to work, students have to launch each Perusall assignment from an assignment-specific link in your LMS (i.e., one with a name that matches the title of an assignment in Perusall). During that launch process, the LMS passes information to Perusall that tells Perusall where to send the grade for that student back to.

If you have a grade for a student that isn't syncing back to Perusall, it may be because the student launched Perusall from a generic LTI link and navigated to an assignment within Perusall (so Perusall won't be able to sync the student's grade on that assignment back to Perusall).

However, this can be fixed retroactively -- if the student launches the Perusall assignment from the corresponding assignment-specific link in the LMS (and then just closes the browser, if the assignment is already complete), that will allow the LMS to send the information to Perusall it needs to do a grade sync, and that student's grade will then be queued to send back to LMS in the next sync (Perusall syncs grades about once an hour).

Ensure that assignments are worth the same number of points in the LMS as they are in Perusall

Due to the way LTI works, grades are sent to the LMS as a percentage, rather than as a raw score. The LMS will then apply that percentage to the assignment based on the number of points you have set for that assignment in the LMS. For example, if your lowest possible assignment score is 0 and highest possible assignment score in Perusall is 5, and the assignment is set in the LMS to be worth 10 points, a score of 4 will be sent across to the LMS as 80% and will show up in the LMS as 8/10. For this reason, we recommend that you set up assignments in your LMS to be worth the same number of points as it is worth in Perusall.