Troubleshooting LMS integrations | Perusall

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 "Name only" or "Public.")

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).