At InstructureCon we heard from several of you that migrating from LTI 1.1 to 1.3 has been a challenge. We wanted to ease this as much as possible for both tool developers as well as users of their tools, so we have created this best practices guide. This post does not represent any changes to Canvas services (though we hope to have some updates for you on that front soon!), but instead is intended to help clarify what current functionality is in response to some frequently asked questions. No changes need to be made at this time. This guide is just here to help developers and schools when they choose to upgrade from LTI 1.1 to 1.3.
TL;DR Assignments, line items, and modules will automatically be migrated to use the LTI 1.3 version of a tool when it is hosted on the same domain or a more specific sub-domain as the LTI 1.1 version of the tool. Currently, rich content will automatically launch to the new tool but doesn’t have support for custom variables. We plan to add support in the future. All other resource types have support for custom variables and the relevant LTI APIs, such as Assignment and Grading Services.
Tool Launch Behavior in Canvas
First, some context about current tool launch behavior. Within Canvas, there are multiple ways that a tool is chosen during launch. In some cases, such as launching from the course navigation placement, we have a direct reference to the tool. In other cases, we have an indirect reference to the tool through an associated resource. In either of these cases, finding the correct tool and launching it is relatively easy. In other cases, such as links to tools within rich content, we only have a URL to identify the tool. In cases like this, Canvas sorts all of the tools in a given context based on multiple criteria, including their LTI version. From the beginning of that list, it first searches for a tool that matches the requested URL exactly. If none can be found, it then looks for a tool that matches the URL, ignoring any query parameters that aren’t present in the tool’s launch URL. If a tool still hasn’t been found, it looks for any tool who’s domain or subdomain matches the requested launch URL. Crucially, one of the sorting criteria causes Canvas to prefer LTI 1.3 tools for LTI 1.1 tools. So long as the requested launch URL doesn’t match the launch URL of the LTI 1.1 tool, minus any extra query parameters, the LTI 1.3 tool will be chosen for the launch.
For example, imagine there is an LTI 1.1 tool and an LTI 1.3 tool installed at the course level. The launch URL of the LTI 1.1 tool is https://example.com/launch while the launch URL of the LTI 1.3 tool is https://example.com/1_3/launch . A user then launches a link to the tool from within some rich content, with the link pointing to https://example.com/deep_linking_request . While neither tool matches the URL exactly with their launch URL, their domain does match. Because LTI 1.3 tools are preferred over LTI 1.1 tools, Canvas will launch the LTI 1.3 tool. Additionally, because that launch has an associated LTI 1.1 tool, Canvas will include the LTI 1.1 Migration Claim, which tools can use to migrate and associate LTI 1.1 and LTI 1.3 objects. This claim will include information such as the resource_link_id, oauth_consumer_key , and oauth_consumer_key_sign. Tools can use this information to associate this launch with a previous install of their LTI 1.1 tool.
However, if the requested launch URL was https://example.com/launch?content_id=abcd , Canvas would launch the LTI 1.1 tool instead of the LTI 1.3 tool. In this example, Canvas wouldn’t be able to find any tool that exactly matches the requested launch URL. It would then check the URL against each possible tool’s launch URL, minus the `content_id` parameter, and find the LTI 1.1 tool, whose launch URL is https://example.com/launch . This means that if you want your content to be auto-migrated successfully, you should host your LTI 1.3 tool either on the same domain or a more specific sub-domain of the same domain you host your LTI 1.1 tool on. If you don’t, the migration process will likely miss content which will lead to confusion for both developers and users.
Assignments, Module Items, and Collaborations: Migrating from 1.1 to LTI 1.3 Tools
When you or a customer installs your new LTI 1.3 tool in a context, all assignments, module items, and collaborations that were associated with the LTI 1.1 tool are migrated in the background to use the newly installed LTI 1.3 tool by creating the necessary resources within Canvas, such as resource links. It's important to note that this process is not immediate and can take a variable amount of time depending on how much content needs to be migrated. Additionally, we haven’t migrated content from LTI 1.3 tools that were installed before we made our migration improvements. Once the migration process is complete, you can use the Assignment and Grading Services to interact with the newly migrated assignments, regardless of whether they've been launched by students yet or not, as well as use resource link-level custom variables to request additional information as part of the launch for any of the migrated resources. We have plans to improve visibility into the progress of the migration which will allow administrators and teachers to know when their content has finished migrating and if there were any issues migrating their content.
Rich Content: Migrating from LTI 1.1 to LTI 1.3 Tools
Currently, we do not migrate rich content from LTI 1.1 to LTI 1.3 when a new tool is installed. We have plans to address this limitation of our migration process so that all types of content can be migrated.
More Information:
If you'd like to see a video detailing how the tool lookup process within Canvas works in more detail, please see this video from an April 2023 LTI Roundtable meeting where one of our engineers presented on that topic. This is an area we plan to continue to work on and expand, but we wanted to make the current state transparent to aid in developers and institutions continuing to adopt LTI 1.3.
Note that we do not currently have an end of life date for LTI 1.1. Our focus is on providing feature parity and improved function which will make migrating to LTI 1.3 desirable rather than forced. At least 12 months notice will be provided before any end of life processes begin.
