Developer Platform (January 2020)

LTI Advantage management (registrations, deployments, and links)

«  Assessments and rubrics   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  LTI management (links and tool providers)  »

Contents

The LTI actions let an organization manage the LTI registrations, deployments, and links available to particular organization units. Callers can use these routes to fetch, register, deploy, update, and remove entries for LTI tools and LTI links. Note that each created LTI link will have a unique D2LID assigned so you can identify a link independently of the org unit with which it’s registered; however, you cannot register a single LTI link with more than one org unit. Registrations and deployments can only be created at the organization. These routes apply to LTI 1.3+ only.

Note

These structures and routes apply only to LTI Advantage (LTI v1.3+). You can also refer to the reference for legacy LTI support (LTI v1.1.x).

Attributes

EXTENSION_T

LTI Advantage extensions can have values of a variety of data types; we use the term EXTENSION_T to stand in for an appropriate integer value:

Data type name

Value

AssignmentAndGradeServices

1

DeepLinking

2

NamesAndRoleProvisioningServices

3

LINK_TYPE_T

LTI Advantage Link types can have values of a variety of data types; we use the term LINK_TYPE_T to stand in for an appropriate integer value:

Data type name

Value

Basic

1

Widget

2

Quicklink

3

InsertStuff

4

Tool Registration

LTI.CreateRegistrationData

When a client invokes an action to register or update an already registered LTI tool for an organization, it should provide a structure like this:

{
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "Domain": <string>,
    "RedirectUrls": [ <string>,... ],
    "OpenIDConnectLoginUrl": <string>,
    "KeysetUrl": null|<string>,
    "EnabledExtensions": [ <number:EXTENSION_T>,... ],
    "SendInstitutionRole": <boolean>
}
LTI.RegistrationData

When a client invokes an action that would retrieve the registration information for an LTI tool, the Learning Service sends back a structure like this:

{
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "Domain": <string>,
    "RedirectUrls": [ <string>,... ],
    "OpenIDConnectLoginUrl": <string>,
    "KeysetUrl": <string>,
    "EnabledExtensions": [ <number:EXTENSION_T>,... ],
    "SendInstitutionRole": <boolean>,
    "BrightspaceAudience": <string>,
    "BrightspaceIssuer": <string>,
    "BrightspaceKeysetURL": <string>,
    "BrightspaceOAuth2AccessTokenURL": <string>,
    "BrightspaceOIDCAuthenticationEndpoint": <string>
}
Brightspace* properties

All the Brightspace* properties are Brightspace values that should be shared back to the tool.

Tool Deployment

LTI.CreateDeploymentData

When a client invokes an action to deploy or update an already deployed LTI tool for an organization, it should provide a structure like this:

{
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "EnabledExtensions": [ <number:EXTENSION_T>,... ],
    "Anonymous": <boolean>,
    "SendOrgUnitInformation": <boolean>,
    "SendUserFirstName": <boolean>,
    "SendUserMiddleName": <boolean>,
    "SendUserLastName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendD2LUserId": <boolean>,
    "SendD2LUsername": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "PreProvisioning": <boolean>
}
PreProvisioning

Security setting to send classlist including users not known to tool.

LTI.DeploymentData

When a client invokes an action that would retrieve the deployment information for an LTI tool, the Learning Service sends back a structure like this:

{
    "DeploymentId": <GUID>,
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "EnabledExtensions ": [ <number:EXTENSION_T>,... ],
    "AvailableExtensions": [ <number:EXTENSION_T>,... ],
    "Anonymous": <boolean>,
    "SendOrgUnitInformation": <boolean>,
    "SendUserFirstName": <boolean>,
    "SendUserMiddleName": <boolean>,
    "SendUserLastName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendD2LUserId": <boolean>,
    "SendD2LUsername": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "PreProvisioning": <boolean>,
    "IsAvailable": <boolean>
}
PreProvisioning

Security setting to send classlist including users not known to tool.

AvailableExtensions, EnableExtensions

For an extension to be active it must be in both the AvailableExtensions and EnabledExtensions lists.

Tool Deployment Sharing

LTI.CreateSharingRuleData

When a client invokes an create a sharing rule that will make an LTI Deployment available to an org unit they should send this structure:

{
    "SharingOrgUnitId":  <number:D2LID>,
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>
}
LTI.UpdateSharingRuleData

When a client invokes an update a sharing rule that will make an LTI Deployment available to an org unit they should send this structure:

{
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>
}
LTI.OrgUnitSharingRuleData

When a client invokes an action to retrieve the sharing information for an already registered LTI Deployment they will receive this structure:

{
    "SharingOrgUnitId":  <number:D2LID>,
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>,
    "Inherited": null|<boolean>
}
Inherited

Determines if an org unit has been shared to by having a parent that is shared with all descendants.

Actions

Tool Registration

DELETE /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Remove an LTI Advantage registration.

Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Note

A registration may only be deleted if it is not tied to any deployments.

GET /d2l/api/le/(version)/ltiadvantage/registration/

Retrieve the information for all LTI registrations for the organization.

Parameters
Query Parameters
  • isEnabled (boolean) – Optional. Used to limit registrations based on IsEnabled status.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of registrations belonging to the organization.

GET /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Retrieve the information for a particular LTI registration.

Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the data associated with the matching LTI registration.

POST /d2l/api/le/(version)/ltiadvantage/registration/

Register a new LTI tool for the organization.

Parameters
JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the data associated with the newly created LTI registratation.

PUT /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Update the information associated with an LTI tool registration.

Parameters
JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the updated data for the tool registration.

Tool Deployment

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Remove an LTI Advantage deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Note

A LTI tool deployment may only be deleted if it is not tied to any links.

GET /d2l/api/le/(version)/ltiadvantage/deployment/

Retrieve the information for all LTI deployments for the organization.

Parameters
Query Parameters
  • clientId (D2LID) – Optional. Used to limit deployments based on ClientId value.

  • isEnabled (boolean) – Optional. Used to limit deployments based on IsEnabled status.

  • isAvailable (boolean) – Optional. Used to limit deployments based on IsAvailable status.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of LTI tool deployments belonging to the organization.

GET /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Retrieve the information for a particular LTI tool deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the data associated with the matching LTI tool deployment.

POST /d2l/api/le/(version)/ltiadvantage/deployment/

Create a new LTI tool deployment for the organization.

Parameters
JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the data associated with the newly created LTI tool deployment.

PUT /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Update the information associated with an LTI tool deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the updated data for the LTI tool deployment.

Tool Deployment Sharing

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Delete all sharing rules for a particular LTI deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/(sharingOrgUnitId)

Delete the sharing rule for a particular org unit and LTI deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

  • sharingOrgUnitId (D2LID) – Org unit ID the deployment is shared to.

Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage deployments.

  • 404 Not Found – No such deployment found registered for org or no sharing rule for org unit.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

GET /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Retrieve the sharing rules for a particular LTI deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Query Parameters
  • incldueInherited (boolean) – Optional. Used to include org units shared by inheritence.

  • orgUnitId (D2LID) – Optional. Used to limit to a single org unit.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of OrgUnitSharingRuleData for the deployment.

POST /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Add a sharing rule for a particular LTI deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a CreateSharingRuleData JSON block containing the data associated with the newly registered sharing rule.

PUT /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/(sharingOrgUnitId)

Update the sharing rule for a particular org unit and LTI tool deployment.

Parameters
  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

  • sharingOrgUnitId (D2LID) – Org unit ID the deployment is shared to.

JSON Parameters
Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage deployments.

  • 404 Not Found – No such deployment found registered for org or no sharing rule for the sharingOrgUnitId.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a CreateSharingRuleData JSON block containing the data associated with the newly updated sharing rule.

Links

Remove an LTI Advantage link.

Parameters
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage external learning tool links or Delete External Learning Tool Links.

  • 404 Not Found – No such link found.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Retrieve the information for all LTI Advantage links for the organization.

Parameters
Query Parameters
  • deploymentId (GUID) – Optional. Used to limit links based on deployment.

  • isEnabled (boolean) – Optional. Used to limit links based on IsEnabled status.

  • IsAvailable (boolean) – Optional. Used to limit links based on IsAvailable status.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of Links belonging to the organization.

Retrieve the information for a particular LTI Advantage organization link.

Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the matching LTI Advantage link.

Retrieve the information for all LTI Advantage links within the scope of an org unit.

Parameters
  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

Query Parameters
  • deploymentId (GUID) – Optional. Used to limit links based on deployment.

  • isEnabled (boolean) – Optional. Used to limit links based on IsEnabled status.

  • IsAvailable (boolean) – Optional. Used to limit links based on IsAvailable status.

Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage external learning tool links or create external learning tool links from external learning tool providers or create quicklinks from available external learning tools links.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of Links belonging to the org unit.

Retrieve the information for a particular LTI Advantage link.

Parameters
  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage external learning tool links or create external learning tool links from external learning tool providers or create quicklinks from available external learning tools links.

  • 404 Not Found – No such link found.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the matching LTI Advantage link.

POST /d2l/api/le/(version)/ltiadvantage/links/organization/

Create a new LTI Advantage link for the organization.

Parameters
JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the newly created LTI Advantage link.

POST /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/

Create a new LTI Advantage link for an org unit.

Parameters
  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

JSON Parameters
Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Unable to create link, or bad link data provided.

  • 403 Forbidden – No permission to manage external learning tool links or create external learning tool links from external learning tool providers.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the newly created LTI Advantage link.

POST /d2l/api/le/(apiVersion)/ltiadvantage/quicklinks/orgunit/(orgUnitId)/link/(linkId)

Build a new quicklink around an existing LTI Advantage link.

Parameters
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Input. Provide an empty post body.

Return. This action returns a Quicklink JSON block containing the details for the new quicklink.

Update the information associated with an LTI Advantage link.

Parameters
JSON Parameters
Status Codes
API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the updated data for the LTI Advantage link.

Update the information associated with an LTI Advantage link.

Parameters
  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

  • linkId (D2LID) – Link ID.

JSON Parameters
Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Unable to update LTI Advantage link data.

  • 403 Forbidden – No permission to manage external learning tool links or create external learning tool links from external learning tool providers.

  • 404 Not Found – No such link found.

API Versions
  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the updated data for the LTI Advantage link.

«  Assessments and rubrics   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  LTI management (links and tool providers)  »