Developer Platform (October 2020)

LTI management (links and tool providers)

«  LTI Advantage management (registrations, deployments, and links)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Learning Repository objects  »

Contents

The Learning Tools Interoperability® actions let an organization manage the LTI® tool providers and links available to particular organization units. Callers can use these routes to fetch, register (create), update, and remove entries for LTI tool providers and LTI links. Note that each created LTI tool provider registration will have a unique D2LID assigned (and so will each created LTI link), so you can identify a tool provider or link independently of the org unit with which it’s registered; however, you cannot register a single LTI tool provider or link with more than one org unit.

Note

The LTI API routes are fulfilled by the LE product component and included in the LE API contract version. The ‘lti’ product component listed in version blocks (such as Version.ProductVersions) indicates the level of LTI standard the platform supports, and not the API contract version for these routes.

Attributes

OAUTH_SIGNATURE_METHOD_T

LTI OAuth signature method can have values of a variety of data types; we use the term OAUTH_SIGNATURE_METHOD_T to stand in for an appropriate integer value:

Data type name

Value

HMAC_SHA_1

1

HMAC_SHA_256

2
LTI_VERSION_T

LTI version can have a variety of values; we use the term LTI_VERSION_T to stand in for the appropriate integer value:

Version

Value

Inherit

0

One_One

1

One_One_Two

2
LTI.CreateLtiLinkData

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

{
    "Title": <string>,
    "Url": <string>,
    "Description": <string>,
    "Key": <string>,
    "PlainSecret": <string>,
    "IsVisible": <boolean>,
    "SignMessage": <boolean>,
    "SignWithTc": <boolean>,
    "SendTcInfo": <boolean>,
    "SendContextInfo": <boolean>,
    "SendUserId": <boolean>,
    "SendUserName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "SendD2LUserName": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendD2LOrgRoleId": <boolean>,
    "UseToolProviderSecuritySettings": <boolean>,
    "CustomParameters": null|[ <LTI.CustomParameter>, ... ]
}
CustomParameters

Any custom parameters will get passed as name-value pairs in this property; if no custom parameters are needed for this LTI link, this property will be null.

Description

As this string’s value gets used during the process of generating signatures in the LTI launch process, you should not include CR or LF characters in the string. You can provide simple HTML in the description; however, the back-end service will sanitize it before use, so the actual value used may differ on launch from what you provide.

UseToolProviderSecuritySettings

If true, then this link will use all the Send* properties defined for the associated Tool Provider entry (as determined by URL matching against Tool Provider definitions).

LTI.CustomParameter

Encapsulates a custom LTI parameter in a name-value pair.

{
    "Name": <string>,
    "Value": <string>
}
LTI.LtiLinkData

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

{
    "LtiLinkId": <number:D2LID>,
    "Title": <string>,
    "Url": <string>,
    "Description": <string>,
    "Key": <string>,
    "IsVisible": <boolean>,
    "SignMessage": <boolean>,
    "SignWithTc": <boolean>,
    "SendTcInfo": <boolean>,
    "SendContextInfo": <boolean>,
    "SendUserId": <boolean>,
    "SendUserName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "SendD2LUserName": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendD2LOrgRoleId": <boolean>,
    "UseToolProviderSecuritySettings": <boolean>,
    "CustomParameters": null|[ <LTI.CustomParameter>, ... ]
}
UseToolProviderSecuritySettings

If true, then this link will use all the Send* properties defined for the associated Tool Provider entry (as determined by URL matching against Tool Provider definitions). Assumed to be False, by default.

LTI.LtiQuickLinkData

When a client creates a new quicklink around an existing LTI link, the service returns a structure like this to describe the new quicklink:

{
    "LtiLinkId": <number:D2LID>,
    "PublicUrl": <string>
}
PublicUrl

This property contains the URL location for the new quicklink.

LTI.CreateLtiProviderData

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

{
    "LaunchPoint": <string>,
    "Secret": <string>,
    "UseDefaultTcInfo": <boolean>,
    "Key": <string>,
    "Name": <string>,
    "Description": <string>,
    "ContactEmail": <string>,
    "IsVisible": <boolean>,
    "SendTcInfo": <boolean>,
    "SendContextInfo": <boolean>,
    "SendUserId": <boolean>,
    "SendUserName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "SendD2LUserName": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendD2LOrgRoleId": <boolean>,
    "OAuthSignatureMethod": <number:OAUTH_SIGNATURE_METHOD_T>,
    "Version" : <number:LTI_VERSION_T>
}
Send* properties

The list of Send* properties allow these security settings defined at the Tool Provider level to override security settings defined with any of the associated LTI Link definitions (as determined by matching LTI link Url properties aginst the Tool Provider’s LaunchPoint property).

OAuthSignatureMethod property

Available as of API version 1.42

Version property

Available as of API version 1.48

LTI.LtiToolProviderData

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

{
    "LtiToolProviderId": <number:D2LID>,
    "OrgUnitId": <number:D2LID>,
    "LaunchPoint": <string>,
    "UseDefaultTcInfo": <boolean>,
    "Key": <string>,
    "Name": <string>,
    "Description": <string>,
    "ContactEmail": <string>,
    "IsVisible": <boolean>,
    "SendTcInfo": <boolean>,
    "SendContextInfo": <boolean>,
    "SendUserId": <boolean>,
    "SendUserName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "SendD2LUserName": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendD2LOrgRoleId": <boolean>,
    "OAuthSignatureMethod": <number:OAUTH_SIGNATURE_METHOD_T>,
    "Version" : <number:LTI_VERSION_T>
}
Send* properties

The list of Send* properties allow these security settings defined at the Tool Provider level to override security settings defined with any of the associated LTI Link definitions (as determined by matching LTI link Url properties against the Tool Provider’s LaunchPoint property).

OAuthSignatureMethod property

Available as of API version 1.42

Version property

Available as of API version 1.48

LTI.CreateSharingRule

When a client invokes an action to create or update an already registered LTI Tool Provider to be shared to another org unit they should send this structure:

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

The org unit to share the tool provider to; the org unit must be a descendant of the org unit that the tool provider was created in.

ShareWithOrgUnit

Determines if the tool provider is shared with the SharingOrgUnitId.

ShareWithDescendants

Determines if the tool provider is shared with all descendants of the SharingOrgUnitId.

LTI.SharingRuleWithDescendantTypes

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

{
    "SharingOrgUnitId":  <number:D2LID>,
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>,
    "DescendantsTypes: null | [<OrgUnitTypeId>, ...]"
}
SharingOrgUnitId

The org unit that the tool provider is shared with.

ShareWithOrgUnit

Determines if the tool provider is shared with the SharingOrgUnitId.

ShareWithDescendants

Determines if the tool provider is shared with descendants of the SharingOrgUnitId.

DescendantsTypes

A list of org unit types that this tool provider is shared with or null if the tool provider is shared with all descendant org units.

LTI.UpdateSharingRule

When a client invokes an action to update the sharing rule of an LTI Tool Provider they should send this structure:

{
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>
}
ShareWithOrgUnit

Determines if the tool provider is shared with the SharingOrgUnitId.

ShareWithDescendants

Determines if the tool provider is shared with all descendants of the SharingOrgUnitId.

Actions

LTI Tool Providers

DELETE /d2l/api/le/(version)/lti/tp/(tpId)

Remove the registration for an LTI tool provider.

Parameters
Status Codes
API Versions

  • 1.34+ – Route first appears in LMS v20.19.5.

  • 1.27-1.33 – Deprecated as of LMS v20.20.1.

  • 1.26- – Obsolete as of LMS v20.20.1.

GET /d2l/api/le/(version)/lti/tp/(orgUnitId)/

Retrieve the information for all LTI tool providers registered for an org unit.

Parameters
Status Codes
API Versions

  • 1.34+ – Route first appears in LMS v20.19.5.

  • 1.27-1.33 – Deprecated as of LMS v20.20.1.

  • 1.26- – Obsolete as of LMS v20.20.1.

Return. This action returns a JSON array of LtiToolProviderData data blocks, containing the details for all the tool providers registered for the provided org unit.

GET /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)

Retrieve the information for a particular LTI tool provider.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

Status Codes
API Versions

  • 1.34+ – Route first appears in LMS v20.19.5.

  • 1.27-1.33 – Deprecated as of LMS v20.20.1.

  • 1.26- – Obsolete as of LMS v20.20.1.

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

POST /d2l/api/le/(version)/lti/tp/(orgUnitId)

Register a new LTI tool provider for an org unit.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.34+ – Route first appears in LMS v20.19.5.

  • 1.27-1.33 – Deprecated as of LMS v20.20.1.

  • 1.26- – Obsolete as of LMS v20.20.1.

Return. This action returns a LtiToolProviderData JSON block containing the data associated with the newly registered LTI tool provider.

PUT /d2l/api/le/(version)/lti/tp/(tpId)

Update the information associated with a registered LTI tool provider.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.34+ – Route first appears in LMS v20.19.5.

  • 1.27-1.33 – Deprecated as of LMS v20.20.1.

  • 1.26- – Obsolete as of LMS v20.20.1.

Return. This action returns a LtiToolProviderData JSON block containing the updated data for the tool provider.

LTI Tool Provider Sharing

DELETE /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)/sharing/

Delete all sharing rules for a particular LTI tool provider.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

Status Codes
API Versions

  • 1.38+ – Route first appears in LMS v20.19.11.

DELETE /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)/sharing/(sharingOrgUnitId)

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

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

Status Codes
API Versions

  • 1.38+ – Route first appears in LMS v20.19.11.

GET /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)/sharing/

Retrieve the sharing rules for a particular LTI tool provider.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

Status Codes
API Versions

  • 1.38+ – Route first appears in LMS v20.19.11.

Return. This action returns a list of SharingRuleWithDescendantTypes JSON blocks containing the data associated with the matching LTI tool provider.

POST /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)/sharing/

Add a sharing rule for a particular LTI tool provider.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

JSON Parameters
Status Codes
API Versions

  • 1.38+ – Route first appears in LMS v20.19.11.

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

PUT /d2l/api/le/(version)/lti/tp/(orgUnitId)/(tpId)/sharing/(sharingOrgUnitId)

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

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • tpId (D2LID) – Tool provider ID.

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

JSON Parameters

  • UpdateSharingRule – Data for a new or updated sharing rule.

Status Codes
API Versions

  • 1.38+ – Route first appears in LMS v20.19.11.

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

«  LTI Advantage management (registrations, deployments, and links)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Learning Repository objects  »