Skip navigation
All Places > Canvas Developers > Blog > Author: Jesse Poulos

Canvas Developers

2 Posts authored by: Jesse Poulos Employee

Overview

One of the most common questions I'm asked when consulting our Canvas partners is how to synchronize the roster from Canvas into an external application. There are a variety of ways this can be accomplished, each with their advantages and disadvantages depending on the needs of your product and customers. This post is meant to be a resource for external tool providers hoping to maintain a synchronized roster between their systems and Canvas.

LTI-only Workflow

Requirements

This approach requires an LTI integration to be configured and visible somewhere within a Canvas course. Ideally, this LTI connection will already have an LTI SSO mechanism. If username, login ID, email, and/or SIS ID is required, make sure the privacy level is set to Public in the tool configuration. Otherwise, Canvas will only send an opaque LTI user id (as the user_id parameter) and a Canvas ID (as the custom_canvas_user_id).

Advantages

  • API access not required
  • Interoperable
  • Can provision users on-the-fly as they launch the tool

Limitations/Challenges

  • LTI tool is only aware of users who've launched their tool at least once
  • Unidirectional: cannot push new enrollments to Canvas
  • Cannot determine if users drop courses or are deleted from Canvas

Instructor/Admin/Student Workflow

  1. Configure an LTI tool in Canvas
  2. Launch the tool
  3. Tool consumes user information (name, email, ID's, roles, contextual information etc...) and attempts to match on an ID. Best practice is to match on the user_id from the launch and then fall back to some other ID if a match is not found
  4. If a match is confirmed (and the signature matches), let the user access their information in your application
  5. If no match is found, either or send them through a user-creation flow within the iframe, or auto-create a user for them based on the information in Canvas (you may want to let them set a password at this point, or email them a registration URL)

LTI + API Workflow

The main limitation of the LTI-only workflow is that it requires users to launch the tool through the LMS. This often does not make sense. For example, some tools are used only by instructors, so there is no opportunity for the students to launch an LTI tool. The LTI + API workflow works best for tools targeting teachers or students, but is limited when synchronizing rosters for large accounts.

Requirements

This approach requires an LTI integration to be configured. It also must use OAuth2 to obtain instructor and student API tokens.

Advantages

  • Can provision entire courses or sections with a teacher token, or entire accounts with an admin token
  • Can remove/hide users that have dropped courses or have been deleted
  • Bi-directional: if authorizing user has permissions, can create/update/delete enrollments within Canvas

Limitations/Challenges

  • Requires implementation of OAuth2
  • Requires heavy usage of Canvas-specific API’s making it not interoperable
  • If attempting to sync entire accounts, can be slow for large accounts due to API throttling

Admin Workflow

  1. Admin launches the tool from account navigation or elsewhere
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
  3. Tool retrieves a list of courses via the accounts API, then uses the Enrollments API for each course
  4. Tool can then create/update/delete users from their database based on the results


NOTE: This approach is not recommended for large accounts due to API throttling. Instead, either use the LTI + SIS + API approach in the next section or see the Instructor Workflow below.

Instructor Workflow

  1. Instructor launches the tool from course navigation or elsewhere
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
  3. Tool consumes the custom_canvas_api_domain and custom_canvas_course_id from the LTI launch and checks the Enrollments API for the course. Alternatively, the tool can check the enrollments for the instructor to sync all courses they are enrolled in; this requires consuming the custom_canvas_user_id
  4. Tool can then create/update/delete users from their database based on the results

Student Workflow

  1. Student launches the tool from the course
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
  3. Tool consumes the custom_canvas_course_id from the LTI launch and checks the Enrollments API for the course


NOTE: Some students may not have permission to view the list of users in their course.

LTI + Reports API Workflow

The main limitation of the LTI + API workflow is that it doesn’t work well for large accounts. By using the Reports API, tools can generate reports that list all users in an account. This is best used for institutions who’ve implemented SIS, but it’s not a requirement.

Advantages

  • Can provision entire accounts without worry of being throttled
  • Can remove/hide users who have dropped courses or have been deleted
  • Bi-directional: if authorizing user has permissions, can create/update/delete enrollments within Canvas via SIS Imports API

Limitations/Challenges

  • Requires an admin-level token
  • Best if institution has implemented SIS; SIS exports only show resources with SIS ID's. If SIS ID's are absent, you'll need to understand how to interpret the provisioning report
  • Requires implementation of OAuth2
  • Requires heavy usage of Canvas-specific API’s making it not interoperable
  • Requires parsing CSV's and downloading files
  • Requires understanding the structure of SIS CSV files or the provisioning report

Admin Workflow

  1. Admin launches the tool from account navigation
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
  3. Tool starts a report via API


NOTE: There are two reports of interest here. The easiest to interpret is the SIS Export report; however, the SIS Export report only shows users with SIS ID's. In this scenario, you’ll need to rely on the provisioning report instead.

  1. Tool polls the report to check progress
  2. When the report is complete, tool downloads the report and parses the data to synchronize users
  3. Tool can then create/update/delete users from their database based on the results

Instructor/Student Workflow

Instructors and students don’t have access to the reports API. However, the same functionality of the LTI + API integration described in previous sections can still be used to compliment the LTI + Reports API workflow. For example, you may want to do a nightly sync at the account level, but still use API + LTI to synchronize data when a user launches the tool.

NOTE: Admins can also manually send reports to a tool provider for one-time provisioning of new customers; however, in order to maintain an accurate list of users and enrollments, the tool would still need to sync data via LTI and/or API.

NOTE: The workflows which leverage API can be further automated or simplified by obtaining an admin token with the “become other users” permission. This token can then be used to make API requests on behalf of teachers and students by appending as_user_id=<student/teacher user id>. However, this can be problematic for high numbers of assignments or students as you’ll likely experience throttling issues.

SIS-only Integrations

This won’t be discussed here. For more information about integrating with Canvas as a SIS provider, please contact: Chase Pendleton <cpendleton@instructure.com> (SIS Partnerships Manager)

Roadmap: LTI Names and Role Provisioning Services (Membership Service)

We’re currently working toward implementation of the IMS LTI Names and Role Provisioning Service. We hope to have most, if not all, of the service implemented by the end of 2018. This service will make the LTI-only workflow more useful for instructors in particular as it doesn’t require all users in a course to launch the tool, and it'll allow tools to be aware of changes in the course roster.

Requirements

The requirements are the same as the LTI-only workflow outlined above, but you must also conform to the IMS LTI Names and Role provisioning Service as a tool provider.

Advantages

  • Does not require API access
  • Can provision an entire course on-the-fly when an instructor or admin launches a tool from the course
  • Interoperable

Limitations/Challenges

  • Will not be able to synchronize an entire account
  • Launch must occur in the context of a course
  • Unidirectional: cannot push new enrollments to Canvas

Workflow

  • User launches tool from course
  • Canvas sends a service URL that a tool can use to see a full list of users for the course
  • Tool can then create/update/delete users from their database based on the results

Concluding Remarks

This isn’t a comprehensive guide to solving the challenge of synchronizing users and enrollments between systems. I encourage creativity and product discovery with your customers to see how they envision your product working within Canvas. My hope is that this guide has at least allowed you to gain a better understanding of what is and isn’t possible so your organization can make decisions that help our mutual users have the greatest experience possible.

 

For those who’ve already solved this problem, how has your integration combined API and LTI to provision users from Canvas? Are there any interesting approaches you've taken that I haven’t considered here? Please share in the comments!


Jesse Poulos
Partner Integrations Specialist
Instructure

Overview

 

As Instructure's Partner Integrations Specialist, I’m often asked how an LTI tool can return a grade to Canvas for an assessment that’s completed on the tool provider side. The answer varies based on a set of requirements the tool provider has. However, I’ve outlined the most common workflows I encounter to hopefully help others find the right place to start—keep in mind that a combination of these workflows can also be utilized, you don’t have to choose just one.

 

LTI-only Workflow

Requirements

 

This approach requires an LTI integration to be configured with an assignment_selection placement and a content item selection request. It should also be capable of executing the LTI Outcomes service.


Advantages

  • API access not required
  • Interoperable
  • Can return LTI Launch URL as submission, allowing the tool to iframe a submission on the submission details page and within Speedgrader without the user having to leave Canvas
  • Grades applied using the LTI Outcomes service will also mark the student as having completed the assignment; this isn’t the case when a grade is returned via Submissions API

 

Limitations

  • Teacher must manually configure each external tool assignment using content item selection
  • Student must launch each assignment so the tool can collect required information
    • As a result, a tool can’t have a series of assessments where grades are returned to separate assignments unless they provide the content as a common cartridge

 

Instructor Workflow

  1. Create an assignment in Canvas
  2. Choose “External Tool” as the Submission Type
  3. Choose the tool from the list that appears in the modal
  4. A properly configured tool allows the instructor to then choose a resource
  5. Tool returns a content item message to Canvas with the Launch URL to that resource
  6. Teacher saves and publishes the assignment


Student Workflow

  1. Launch the assignment triggering a launch to the launch URL provided by the tool when the teacher configured the tool
  2. Tool consumes the lis_outcome_service_url and lis_result_sourcedid for the student X assignment combination and stores it
  3. Student completes the assessment
  4. Tool either automatically grades the student, or waits for teacher to grade student
  5. Grade is returned to Canvas via LTI Outcomes service
  6. (optional) Using the LTI Outcomes service, the tool can also return a piece of plain text, a basic URL, or even an LTI Launch URL. This will be attached to a student submission object in Canvas, and it’ll be visible on the student submission page and in Speedgrader

 

LTI + API Approach

There are two flavors of this workflow. One uses the LTI Outcomes service for grading, while the other uses the Canvas submissions API.

Requirements

This approach requires an LTI integration to be configured with at least a course_navigation placement. It also must use OAuth2 to obtain teacher and student tokens.

 

Advantages

  • Allows a single launch point from Canvas (usually from course navigation) where a student can complete many assessments and have the tool provision assignments within Canvas on the fly and grade them as needed
  • Less manual work for the teacher
  • Organization of assessments can be offered either on the tool side, or by leveraging the Modules page in Canvas
  • Content-Item not required
  • Tools can create external tool assignments and use the API to simulate a student launching the tool in order to obtain data required for the LTI Outcomes service

 

Limitations

  • Requires OAuth2 to obtain either a Canvas API token for teachers (to grade) and students (to optionally submit)
  • Requires heavy usage of Canvas specific API’s, so is not interoperable
  • If grading is achieved via submission API, submissions are not marked complete after a grade is applied. The tool must also submit to the assignment using the submission API to mark complete. Furthermore, only plain text or URL’s can be provided

 

Instructor Workflow

  1. Instructor launches the tool from course navigation or elsewhere and assigns the available work to students, or the tool can do this automatically
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a teacher token
  3. Tool creates external tool assignments using the Assignments API. These assignments should have an LTI Launch URL that has query parameters for the assignment, or the path that launches directly to the assignment, e.g. https://some_launch.com/assignment/<tools_assignment_id> or https://some_launch.com?assignment_id=<tools_assignment_id>

 

Student Workflow

  1. Student launches the tool from the course navigation button
  2. Tool kicks off OAuth2 if it needs to obtain or refresh a student token
    1. Student picks the assignment within the tool and completes it
    2. Tool grades and submits the assessment to Canvas
      • Option 1: LTI for grading
        • Tool uses the sessionless launch API as the student to launch the tool
        • Tool consumes the lis_outcome_service_url and lis_result_sourcedid for the student X assignment combination and stores it
        • Tool uses the IMS Outcomes service to return a grade and an LTI Launch URL to their submission
      • Option 2: API for grading
        • Tool uses the Submissions API as the teacher to grade the student
        • (optional) Tool uses the Submissions API as the student to submit so the teacher can verify students completed the assessment

     

    NOTE: The process can be further automated/simplified by obtaining an admin token with the “become other users” permission. This token can then be used to make API requests on behalf of teachers and students by appending the as_user_id=<student/teacher user id>. However, this can be problematic for high numbers of assignments or students as you’ll likely experience throttling issues.

    I always like to hear about creative ways for integrations to grade and submit assignments. How has your integration combined API and LTI to grade and submit to Canvas?