Recommended Testing Procedure
The generally-recommended process for testing to ensure migration is successful is the three-step process shown below but completed in a testing environment. Before completing this workflow, it is recommended that the admin has received confirmation that the tool is ready for migration to 1.3; and the admin must also be familiar enough with the tool functionality to check the migrated link and confirm that it’s working as needed.
- Set up a new LTI Advantage Tool registration. Then set up a deployment in a sandbox area, turn on the Auto Migrate Link toggle, enable the deployment, and share the deployment to the testing sandbox.
- Create a brand new LTI Advantage link in the destination course. Next, create a 1.1 link in a source course and run the copy job; or trigger a manual migration by pressing the manual migrate button to uplift the link to 1.3.
- Test both the manually-created link and the migrated link to ensure behaviour is working as expected for both. This will require knowledge on what the tool is expected to do. It is recommended that the administrator completing this workflow knows the tool is ready to migrate to 1.3 and is familiar with the functionality of the tool.
Troubleshooting Broken Course Links
In rare occasions, LTI links can be migrated successfully from 1.1 to 1.3 as reported in the migration audit table, but this can still result in a non-functional link in the course. It is recommended to check every link that is migrated to ensure the migration process was successful.
Links can only be migrated from legacy 1.1 to 1.3 advantage, and migration cannot be reversed. If a course link is broken after migrating, the link will need to be deleted and re-migrated after the migration issue has been resolved.
Migration can be successfully completed from 1.1 link URL https://example.com/v1p1, to domain https://example.com/v1p3, but may still result in a broken course link because the course link URL will remain https://example.com/v1p1 after the migration process, and the tool may be expecting the new 1.3 https://example.com/v1p3. To work around this the link must be manually updated in place with the new 1.3 URL.
Q: How do I stop the migration process?
A: The migration process can be prevented by changing to Disabled for the Auto Migrate Links toggle switch, removing the sharing rule for the course, or by disabling the deployment or registration.
Figure: The Auto Migrate Links toggle switch or the manual migration button controls when migration happens on course copy.
Figure: The Add Org Units option. Remove sharing rules for an LTI link by going to External Tools > LTI Advantage > Deployment.
Figure: Disable an LTI link deployment by going to External Learning Tools > LTI Advantage > Deployment.
Figure: Disable the LTI 1.3 registration by going to Manage Extensibility > LTI Advantage > Registration.
Q: Can I opt out of migration?
A: Yes, there is a toggle to disable the migration process for each deployment. It can be found in external learning tools for each deployment.
Figure: The Auto Migrate Links toggle switch controls when migration happens on course copy or by the manual migration button.
Q: Why does my migrated course link not work when the migration audit table shows it was a completed migration?
A: The audit table shows ‘complete’ when a matching registration and deployment is found and the link was migrated to 1.3. It does not validate that a launch will be successful in the course. There is likely a problem with the link on the tool side.
Domain Matching
Q: My domain for 1.3 is slightly different than for 1.1, why won’t it migrate?
A: An exact domain match between the link and the registration is needed. The only exception is that the URL will be updated from http to https. Adding “1.3.”, “advantage.” or any other changes to the domain or subdomain will prevent the migration from being attempted.
Figure: Find the domain for your LTI 1.3 registration at Manage Extensibility > LTI Advantage > Registration. The domain must match the URL for the 1.1 link.
Figure: The LTI 1.1 URL is shown by going to your course > admin > external learning tools > legacy links. The location must match the LTI 1.3 link domain in order for migration to be attempted.
Q: Does migration support subdomain matching?
A: No, subdomains are treated like separate registrations. There is a section in the LTI implementation guide regarding wildcarding that allows for variances in domain names. D2L currently does not support this aspect of the spec but has plans to implement it in 2023.
Q: Does migration consider URL paths, file extensions, queries, parameters, fragments, anchors?
A: No, the auto migration process ignores all information after the domain.
Q: Why did my link shared from another org unit fail to migrate?
A: Links shared from other org units will not be migrated even if they look eligible based on domain matching. The link migration API allows shared links to be migrated. Ensure that the deployment has the same set of sharing rules as the link.
Domain Matching Example
For example, if the 1.3 registration domain for your tool is https://example.com/lti, then the following 1.1 links will be processed as shown below:
- Link https://example.com/lti/link/123 matches the registration because the paths are ignored.
- Link https://example.com/abc matches the registration because the path is ignored.
- Link https://example.com matches the registration because the path is ignored.
- Link https://advantage.example.com does not match the registration, because the subdomain is different.
- Link https://example.ca/lti does not match the registration because the domain is different.
Grades
Q: I’ve used Valence APIs to create multiple 1.1 grade associations. Will they migrate?
A: No, the current migration processes do not support migration of multiple grade book entries. This is planned to be addressed in early CY 2023. D2L plans to provide additional APIs that tools can use to migrate multiple 1.1 grade entries to 1.3.
Q: My grades have been migrated to 1.3 but the tool fails to send the grades.
A: Tools can only send grades if AGS is enabled. To ensure tools have full functionality after migration, enable the Assignment and Grade Services extension for both the registration and deployment.
Visibility/Enabled
Q: Why are there more links in the Content-> Existing Activities -> External Learning Tools window after migration?
Figure: The Add Activity dialog for LTI Advantage Deployment.
A: The Visibility setting is not supported in 1.3. Advantage 1.3 only supports Enabled. When links are migrated to 1.3, they are enabled by default. Some of the new links in this window may have been set to invisible in 1.1.
Course Import
Migration on Course Import does not follow the same process as migration on Course Copy or Button Migration. Since an imported course might come from Brightspace or any other LMS, we follow the common cartridge best practices. Course import migration is not controlled by the Auto Migrate Links toggle.
Note:
- The version of the source link is unknown if the LTI source links were 1.1 or 1.3.
- The same domain matching rules apply. If there are multiple deployments, the most recently-modified deployment will be chosen.
