Integrations Documentation

LTI Migration

Brightspace users can continue to use Legacy LTI implementations in Brightspace.

This is the lightbulb icon used for tips.

Tip: For more information about the end of life for the Legacy LTI tools, refer to LTI 1.1 Deprecation Plan.

However, D2L supports the following methods of migrating existing Legacy LTI Links (1.1.x) to LTI Advantage (1.3):

Migration Domain Mapping APIs
Manual links migration by clicking the Migrate button on the Manage Tool Links (Legacy) tab.
Migration through a Brightspace API.
Course Import.
Course Copy.

Note: For Course Import, Course Copy, and manual links migration, you can use the Migration Domain Mapping API to migrate to a different domain.

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.

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 Domain Mapping APIs

The set of Migration Domain Mapping APIs enables migration from one or more Legacy Link URLs to a different Advantage Registration Domain. Use cases include adding, removing, or updating legacy domains, as well as migrating multiple legacy link URLs to a different Advantage Registration Domain. For more details, refer to Valence documentation.

You must have Legacy Domains as the end point.

After migrations are complete, D2L recommends you un-map these domains. When a legacy domain is mapped, new registrations cannot be made with that legacy domain. For example, if the legacy link URL legacy.com was mapped to the new advantage.com registration domain, creating a new 1.3 registration using the legacy.com domain would not be possible until the mapping is removed.

The migration functionality does not allow the path to be updated, or custom parameters to be updated through the migration process.

As shown in the table below, the path from the Legacy Link URL is carried through to the Link URL after migration.

Example of a user case	Legacy Link URL	Advantage Registration Domain	Mapped Domain	Link URL after Migration
Subdomain change	subdomain1.primary.com/path1	domain3.com	domain1.com	domain3.com/path1
Subdomain and Domain change	subdomain1.domain2.com/path1	domain3.com	domain2.com	domain3.com/path1
Subdomain removal and Domain change	domain2.com/path1	domain3.com	domain2.com	domain3.com/path1
Multiple Legacy Link URL Mapping	domain2.com; subdomain1.domain2.com	domain3.com	domain2.com	domain3.com

In this table:

The Legacy Link URL can be located at the course level by navigating to Course Admin > External Learning Tools > Manage Tool Links (Legacy).
The Advantage Registration Domain is accessible via Admin Tools> Manage Extensibility > LTI Advantage, and then by choosing your registration. Click View Deployments and select your deployment. To ensure it is shared where migration is required, add organizational units in the Make tool available to section and click Add Org Units.
The Link URL after Migration can be found at the course level by going to Course Admin > External Learning Tools > LTI Advantage.

Migration after domain mapping uses the current migration process. It requires registering and deploying the Advantage 1.3 tool to the courses or org units where migration is needed. A migration log entry is recorded for each migration job under Course Admin > External Learning Tools > Migration Log.

Migration jobs for failed migration due to domain matching requirements are identified in the No Domain Match column of the Migration Log. To learn more, refer to the Migration Log section of this topic.

For more details on how these APIs are used, refer to the API Cookbooks in our Community Development category and the corresponding Valence documentation.

Once this mapping is completed, migrations can proceed through standard processes such as Course Import, Course Copy, and manual links migration using the Migrate button. If there are eligible links for the mapped domains, they are migrated to version 1.3. The migration API, which migrates links one at a time, does not work with mapped legacy domains.

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: Click 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.

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.

The Migration Log page and table located in External Learning Tools

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.

The Job Id link of the Migration Log tab

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. The Result field summarizes migration results.

The Migration Log tab showing a report for a migration job. A filter for start dates is applied at the bottom.

Figure: Use the Migration Details section of the Migration Job Report page with shortcuts to the tool deployment page for troubleshooting.

For successful migrations, information in the Migration Details section includes the following:

Deployment
Registration
Domain
Link URL
Legacy Domain (if a legacy link differs from a 1.3 registration domain)

Figure: Navigate to Migration Details of the Migration Job Report page to view information about migrations.

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.
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 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.
The migration process ignores the path of the 1.3 registration domain.

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: Use 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. The Result field summarizes migration results.
Figure: Use the Migration Details section of the Migration Job Report page, with shortcuts to the tool deployment page for troubleshooting.
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.