This article is designed to be a technical specification for LTI integration with the Concourse platform. If you haven't learned the basics about Integration with Concourse and your external systems, consider reading the following:
- Integration Options
- LMS Integration
- Integrating Concourse
This article expands upon advanced topics regarding LTI integration with Concourse. It is suggested that you review the main LTI article before continuing with this one. Additionally, you will likely benefit from reading through a third article that covers LTI setup with your specific LMS.
Apidapter is the middleware tool Concourse utilizes to simplify LTI integrations. Apidapter enables you to:
- handle all mapping and formatting of launch parameters and values prior to reaching Concourse
- log transactions for easy debugging
- allow for the mixing of system end-point protocols
Apidapter simplifies the integration process. For more information on this middleware tool, consider checking out the Apidapter website
Passing user and course identifiers is the most important step in working with LTI. As of May 2015 Concourse now only accepts the standard Learning Information Services (LIS) user and course identifiers in favor of utilizing integration middleware such as Apidapter. Concourse then provides the following options for identification:
- lis_person_sourcedid (matches Concourse external user IDs)
Note: If you choose a user identifier and leave the course identifier at None, users will be logged in and directed to the homepage. Conversely, if you choose a course identifier and set user identifier to None, the user will be brought to the public view for the course and not logged in.
To determine what parameters are available from your LMS you can set a custom parameter of debug=1. Alternatively, you can use Apidapter to log and review launches and uncover the data available to you. This platform will also be beneficial should you need to modify or add any data during the launch.
Ultimately you should try to pick an identification scheme that is consistent with other campus systems, such as your central authentication server and SIS.
The LTI standard lays out a number of context-level roles (e.g. ContentDeveloper) that are similar to groups in Concourse. Below is a chart of how these roles map to each of the Concourse groups. In the event a SubRoleType is used (e.g. Instructor/GuestInstructor) Concourse will consider the root handle (e.g. Instructor).
|LTI Context Role ||Concourse Group|
If your Concourse LTI consumer is configured with both user and course ID's, a user will automatically be enrolled within the course according to this chart upon each LTI launch. That also means if the role of the user changes within the LMS course, their next launch will update their Concourse registration to utilize the new role.
If more than one context role is included the highest role is assumed. In order of descending priority this includes: Managers, Developers, Instructors, Assistants, Students, Guests, Public.
In cases where this is no equivalent group for the given context role, no enrollment will occur and the user will instead be shown the guest view.
Concourse can be configured to automatically create users and/or courses upon LTI launches. The use of this option greatly reduces the complexity of an implementation because feeds do not need to be run to bulk populate users, courses, and registrations.
The auto generation of user accounts is relatively straightforward, requiring only the user ID and their email. Concourse will also process the first and last names if available. However automatic course creation is more complex as LTI launches do not always include all the data parameters required for a new course.
There are other considerations regarding automatic creation. First and foremost you need to be sure that your configuration will lead to a lasting situation. It would be easy to pass the IDs (e.g. user_id and context_id) used by the LMS but should you ever be interested in tighter integration using feed processing your existing data will unfortunately not line up.
Further you may not have direct control over who is able to provision an account or course. Access will be determined by who can enter the LMS, what courses they are a part of, and with what role.
To get started with auto creation refer to the Creating Courses and Users Automatically via LTI article.
The only custom parameter supported by Concourse during LTI launches is one for triggering debug mode. If set (i.e. debug=1) an array of LTI parameters and values will be presented. This is particularly powerful when initially setting LTI up to understand what the LMS is capable of providing.
Non-Standard Parameters and Partial Values
Should you find that your LTI launch is producing non-standard parameter names (e.g. in the case of Canvas, custom_canvas_user_login_id vs. lis_person_sourcedid) or the values need to be manipulated in some way (e.g. turn a course ID of ACCT1010_SP15_2A into ACC-1010-SPRING-15) there is a simple integration middleware tool that can be used to handle these sorts of remapping and data transformations on-the-fly called Apidapter
Apidapter also has the advantage of being able to log transactions for easy debugging and even allow for the mixing of system end-point protocols (e.g. LDAP in, LTI out).
If you find that LTI is not working, there are a number of routes you can investigate.
Are the key and secret identical between Concourse and your other system? Remember these are case-sensitive.
Is the endpoint URL correct? Is should be of the form https://yourdomain.campusconcourse.com/.
- Is the right data being passed? You can set debug=1 as a custom parameter on the LMS side to view an array of all the parameters and values your system is able to provide to help with discovery.
- Is the page "breaking out" when you want it to load within the LMS window? Adjust the embed mode toggle to keep Concourse "inside."
If selected, does the launch contain lis_person_sourcedid?
Does the user exist in Concourse and does the identifier match what the launch is providing?
Is the user set utilize external authentication? Adjust this on the Admin > User page or through a feed.
- If using auto create, is the email also provided? If so does this email conflict with another user already in the system?
If selected, does the launch contain either lis_course_offering_sourcedid or lis_course_section_sourcedid respectively?
Does the course exist in Concourse and does the identifier match what the launch is providing?
For a detailed guide to LTI errors and resolutions see the attached file. If after trying the suggestions in this guide you are still having trouble getting your LTI integration to work, don't hesitate to reach out.