Brightspace users can continue to use Legacy LTI implementations in Brightspace. However, D2L supports the following methods of migrating existing Legacy LTI Links (1.1.x) to LTI Advantage (1.3):
- Manual links migration by clicking the Migrate button on the Manage Tool Links (Legacy) tab.
- Migration through a Brightspace API
- Course Import.
- Course Copy.
Registration of LTI tools and deployments is a centralized administration workflow in LTI Advantage unlike in Legacy LTI 1.1 or 1.2. The permissions and interfaces for LTI Advantage are different from Legacy LTI 1.1. Ensure that your designated administrators have LTI Advantage permissions to access, monitor, and troubleshoot migration activities.
Manual LTI Links Migration
You can manually migrate LTI 1.1 links to LTI 1.3 by using the Migrate button located on the Manage Tool Links (Legacy) tab of the External Learning Tools page at the Course level.
You must have the Manage LTI Migrations permission enabled for your role to manually migrate LTI links. For all tools you must toggle on the Auto Migrate Links switch. Read more: LTI 1.3 permissions.
Note: The following links are migrated: grades tied to a link created using Basic Outcomes.
The following links are not migrated: sharing rules from the existing tool to the LTI 1.3 tool; grades created using the Valence API.
Migration is only successful if there is an exact match between the link URL and the registration domain. To prevent links from attempting migration, remove the sharing rule for the course or disable the deployment.
To manually migrate LTI links
- On the navbar, click Course Admin.
- Click External Learning Tools.
-
Navigate to the Manage Tool Links (Legacy) tab.
-
Click Migrate.
Figure: The Migrate button of the Manage Tool Links (Legacy) tab.
A migration log opens that displays your migration as queued, in progress, and then complete.
Migration through a Brightspace API
Using the API, an individual LTI link can be migrated. The following LTI types are considered eligible for migration from a legacy to an LTI Advantage tool:
- Basic launches
- Remote plugins: Quicklink CIM, Insert Stuff CIM, and Widgets
The API requires the Legacy LTI 1.1 LinkId, with the LTI Advantage DeploymentId and LTI 1.1 ToolProviderId, which enables D2L to bind the Legacy LTI link to a LTI Advantage deployment.
Note: The ToolProviderId can be null. This should only be the case if the link itself had its own key/secret.
Once a link has been migrated, it no longer appears under the legacy External Learning Tool Links area and is associated to the LTI Advantage deployment. The launch also includes a migration claim, which informs the tool that the link has been uplifted.
Migration via Course Import or Copy
When an IMS Common Cartridge or Brightspace Course Package containing LTI links is imported, Brightspace will default to create those links as LTI Advantage if a matching LTI Advantage tool is set up with registration, deployment, and sharing rules for that course. If there is no matching LTI Advantage tool set up for the course, Brightspace will create those links as Legacy LTI 1.1.
Similarly, users can migrate LTI 1.1 links to LTI Advantage links during course copy. This migration workflow is automatically enabled; however, control over this workflow can be granular. Course links only migrate during copy when:
- The LTI Advantage tool matches the domain of a previous LTI 1.1 tool
- The LTI Advantage tool has a deployment shared to the destination course prior to copy
- The LTI Advantage tool has a deployment with Auto Migrate Links enabled
If there is no corresponding LTI Advantage tool or deployment, the LTI 1.1 link continues to function as expected. This can enable testing of migration prior to fully committing. There is no roll back to LTI 1.1 after a link is migrated to 1.3
When the link has been migrated, it no longer appears under the legacy External Learning Tool Links area and appears under the LTI Advantage area. The link launch will include a migration claim, informing the tool that the link has been migrated.
Migration Log
Users with the View LTI Migration Log permission have access to the Migration Log at the appropriate org unit levels. The log is found in the External Learning Tools interface.
To provide better levels of control for customers with multiple units under one organization, the migration details are locked down based on enrollments and permissions at the course offering level.
The Migration Log tracks all course copies where there are LTI migrations involved and identifies the following:
- The number of Legacy LTI links successfully migrated to LTI Advantage
- The number of Legacy LTI links that had errors (for example, had a matching tool domain found, but no deployments for that course)
- The number of Legacy LTI links that were ignored (no domain match found)
Note: Migrations performed via API or Course Import are not listed in the Migration Log.
You can search and filter the Migration Log results for more detailed information.
Figure: The Migration Log page and table located in External Learning Tools. Click the Status drop-down menu to filter the table results.
Accessing the Migration Log from the course level External Learning Tools page shows all jobs for that course and provides access to the detailed migration log by clicking a link from the Job Id column.
You must have the Manage LTI Migrations or View LTI Migrations Log permission at the Organization and the Course Offering levels to check course migration details.
Figure: Click the Job Id link to view the Migration Details.
For troubleshooting, the Migration Details section of the Migration Job Report page includes shortcuts and the View Developments link, which helps to find matching deployments. This link takes users straight to the deployments page, filtered by registration.
Figure: The Migration Details section of the Migration Job Report page, with shortcuts to the tool deployment page. The Result field summarizes migration results.
The information in the Migration Details section is currently limited to the last 90 days to relevant data available during troubleshooting migrations.
To access data older than 90 days, you can use the LTI Link Migration Audit Brightspace Data Set or Data Hub.
Considerations for Migration
Considerations for the Migration through a Brightspace API
The following list of considerations applies to the migration API only:
- API users must have the Manage LTI Migrations permission. This permission is not required for Course Import or Course Copy for link migrations to occur. D2L recommends granting permission to administrators.
- The LTI Advantage tool registration domain must match the Legacy LTI 1.1 domain for the migration to occur.
- If the legacy link is a CIM, the LTI Advantage tool must have the Deep Linking extension turned on. Otherwise, the API responds with a message.
- If the legacy link is associated with a grade, the LTI Advantage tool must have Assignments, and Grades Services turned on. Otherwise, the API responds with a message.
- When using the API, if the link was created by a remote plugin, it is recommended not to include ToolProviderId whenever possible. Note that if the ToolProviderId is included, it must match the tool provider associated with the remote plugin.
- When using the API, the legacy link or tool provider must have a key and secret.
- When using the API, if the legacy link was shared to a course, the LTI Advantage deployment must be shared to that course.
General considerations
The following list of considerations applies to all migration methods:
- The LTI Advantage tool must have a deployment.
- Custom and/or substitution parameter names for a legacy link must be unique.
- HTML is stripped from the description of a legacy link after migration.
- Migrations are one way, Legacy LTI 1.1 to LTI Advantage, and cannot be reverted.
- If the tool used LTI 1.1 for authentication and Brightspace APIs to create and update grade items in Brightspace, D2L recommends speaking with your tool provider before doing the LTI Advantage migration to ensure there is a plan for API created grade items first.
For more information about setting up an LTI Advantage tool, refer to LTI Advantage Registration.
Troubleshoot Migrations
To find and troubleshoot failed migrations, you can use the following options:
-
To quickly search for the needed deployment if you have large numbers of them, select a registration and filter the results by their Registration Names on the LTI Advantage tab.
Figure: The Registration Names filter on the LTI Advantage tab.
- To get more information about failed migrations, open the Migration Log tab > Migration Details and check shortcuts. You can use the View Developments link to find matching deployments. This link takes you straight to the deployments page, filtered by registration.
Figure: The Migration Details section of the Migration Job Report page, with shortcuts to the tool deployment page. The Result field summarizes migration results.
-
To understand migration status and check links, open the Links page (LTI Advantage > LTI Tool > View Links) and filter results by Type, Status, and Name.
Figure: The Filter by Type option on the Links page.