This documentation provides instructions on how to use the new migration domain mapping API. This workflow will allow migration from one or more 1.1 link URLs to a different 1.3 registration domain, filling the exact domain matching requirement gap.
What it can do
This migration domain mapping API will allow migration from one or more Legacy Link URLs to a different Advantage Registration Domain. Use cases include adding, removing or updating legacy domains and having multiple legacy link URLs migrate to a different advantage registration domain. After this mapping is complete, migrations can be completed through the normal migration processes of course copy, import, or manually with the Migrate button.
For example, links with the follow Legacy Link URLs:
- Domain1.example.com, and
- Domain2.example2.com
Could be migrated to the following registration domain:
Table 1: Migration examples available through Migration Domain Mapping API.
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 | 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 |
What it can’t do
This additional 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 above, the path from the Legacy Link URL is carried through to the Link URL after migration. This additional API only fills the exact domain matching gap; all other limitations and use cases described in the LTI Migration documentation, and Migration FAQs still apply.
The migration API (which migrates a single link at a time) does not work with mapped legacy domains.
How it works
The Legacy Link URL can be found at the course level. Navigate to Course Admin >External Learning Tools > Manage Tool Links (Legacy) and select your link.
Figure: An example of an LTI 1.1 Legacy Link URL.
To view the Advantage Registration Domain, navigate to Admin Tools > Manage Extensibility > LTI Advantage and select your registration.
Figure: An example of an LTI 1.3 Advantage Registration Domain in the Edit LTI Testing Tool dialog.
Migration is only attempted where deployments are shared. You may need to check the sharing rules for a deployment; the customer should provide the correct context for where migration is needed.
From the LTI Advantage tab, click Advantage Tool Registration, and navigate to View Deployments.
Select your deployment, and ensure that it is shared to the migration destination by adding org units in the Make tool available to section. Auto Migrate Links must be enabled.
Figure: The Make tool available to section
The link URL after migration can be found at the course level. Navigate to Course Admin > External Learning Tools > LTI Advantage and select your link.
Figure: The Edit AGS link with dates dialog where you can locate the link URL after migration.
After legacy domains are mapped, migrations can be completed through existing migrations processes of course copy, import, or manually using the Migrate button on the course level Manage Tool Links (Legacy) page.
Steps to Execute
1. Confirm if exact domain matching is the only limitation. The path and any custom parameters cannot be updated. The Manage LTI Advantage Tool Registrations permission is required.
2. With Postman or any other API test tool, use the GET API to find all registrations for the instance. Then copy the ClientID for the desired Advantage Registration Domain that was previously blocked by exact domain matching requirement. This is the LTI Advantage Registration Domain.
GET /d2l/api/le/(version)/ltiadvantage/registration/
3. Use the new Mapping Get API to get available registrations for that ClientId:
GET/d2l/api/le/{version}/ltiadvantage/registration/{clientId}/legacydomains/
This API returns a JSON array of legacy domain strings that are configured for a given LTI Advantage Registration; this initial request should return an empty result.
4. To map a Legacy Link URL to an Advantage Registration Domain, use the POST API. This the legacy link URL column that was previously blocked by the exact domain match limitation, note that https:// is needed. This API can be run multiple times to add to the existing list.
POST/d2l/api/le/{version}/ltiadvantage/registration/{clientId}/legacydomains/
Figure: Use the POST API to map the Legacy Link URL to an Advantage Registration Domain.
5. To map more than one Legacy Link URL to a 1.3 registration, use the PUT API. The PUT API replaces the existing list of mapped URLs.
PUT/d2l/api/le/{version}/ltiadvantage/registration/{clientId}/legacydomains/
Figure: Use the PUT API to map multiple Legacy Link URL to a 1.3 registration.
All future migration events now attempt a migration from the Legacy Link URLs mapped to the 1.3 Domain registration. Migration can be initiated by API, course copy, import, or manually at the course level.
The Link URL after migration labelled has the Path of the Legacy Link URL.
Failed migration jobs are identified in the migration log table with entries in the No Domain Match column.
Figure: The No Domain Match column indicates if there were any migration job failures due to matching issues.
How to stop the Migration Domain Mapping API
To stop this process, request the PUT API with an empty string, this will remove the previously mapped legacy domains.
To immediately stop the migration process, either disable the Auto migrate links toggle at the deployment or remove any sharing rules where migration is not wanted. The integration can be disabled at any time as well, but this also stops the entire integration from working, rather than just migration.
