Developer Platform (April 2024)

Tools

«  API Properties (versions, logging, authentication)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Configuration variables  »

The Tools actions let an organization manage the tools available to an instance: turn them on and off, set org unit defaults, and so forth.

Attributes

Tools.UpdateStatus

When you use an action to update a tool status, you should provide a JSON block like this:

{
    "Status": <boolean>
}

Organization

Tools.OrgInformation

When you make a query about a tool’s information at the organization level (tool status, or its OUDefault property), the service provides a JSON block like this:

{
    "ToolId": <string:D2LID>,
    "DisplayName": <string>,
    "OrgId": <number:D2LID>,
    "Status": <boolean>,
    "OUDefault": <boolean>
}

Org units

Tools.OrgUnitInformation

When you make a query about a tool’s status at the org unit level, the service provides a JSON block like this:

{
    "ToolId": <string:D2LID>,
    "DisplayName": <string>,
    "OrgUnitId": <number:D2LID>,
    "Status": <boolean>,
    "CustomNavbarName": <string>
}
Tools.ToolWithName

When you make a query for a list of tool names, or make a query about a tool’s status at the org unit level and specify the optional query parameter namesOnly, the service provides a JSON block like this:

{
    "ToolId": <string:D2LID>,
    "DisplayName": <string>
}

The DisplayName corresponds to the tool’s CustomNavbarName if that property is not null; otherwise, it corresponds to the tool’s DisplayName. The calling user does not require elevated permissions to retrieve only the tool names.

Actions

Organization

GET /d2l/api/lp/(version)/tools/org/

Retrieve the current organization-level information for all tools.

Parameters:
Query Parameters:

  • includeRestrictedTools (boolean) – Optional. Include restricted tools as possible to retrieve (off by default).

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Note that you can use the includeRestrictedTools query parameter to include restricted tools in the list retrieved with this action; however, these tools still have the property of being restricted (you cannot change their status, etc).

Return. This action returns a paged result set containing the resulting OrgInformation data blocks for the segment following your bookmark parameter (or the first segment, if the parameter is empty or missing).

Note

This action employs the tool’s ToolId property enclosed within the OrgInformation block as the paging control value. You can fetch the segment of results following any tool’s entry in the entire data set by passing that tool’s ToolId as the bookmark value.

GET /d2l/api/lp/(version)/tools/org/(toolId)

Retrieve the current organization-level information for a tool.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns an OrgInformation JSON block, containing information about the provided tool.

PUT /d2l/api/lp/(version)/tools/org/(toolId)

Update the organization-level status for a tool.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an UpdateStatus JSON block for the new status of the provided tool.

PUT /d2l/api/lp/(version)/tools/org/(toolId)/OUDefault

Update a tool’s default status for new org units.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an UpdateStatus JSON block for the new OUDefault value assigned to the provided tool.

Note

This call does not update the org unit status for currently existing org units; it only sets the default value for org units yet to be created.

PUT /d2l/api/lp/(version)/tools/org/(toolId)/OUDefault/override

Update a tool’s current status for all org units.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an UpdateStatus JSON block for the new OUDefault value assigned to the provided tool.

Note

This call will both set the default org unit status for org units yet to be created, and override the status for all existing org units descended from this organization. As a result, this is a system-intensive task and the action will not complete before the action returns.

This action initiates a worker task to complete the action in batches to avoid adversely affecting performance of the back-end service.

Org units

GET /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)

Retrieve the current information for all tools enabled for the provided org unit.

Parameters:
Query Parameters:

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

  • namesOnly (boolean) – Optional. If true, only tool ids and names are returned, and fewer permissions are required.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. If you provide true for the namesOnly query parameter, this action returns a paged result set containing ToolWithName data blocks for the segment following your bookmark query parameter (or the first segment if the bookmark parameter is missing or empty).

If, instead, you provide false for the namesOnly query parameter, or omit it, this action returns a paged result set containing OrgUnitInformation data blocks instead.

Note

This action employs the tool’s ToolId property enclosed within the OrgUnitInformation block as the paging control value. You can fetch the segment of results following any tool’s entry in the entire data set by passing that tool’s ToolId as the bookmark value.

GET /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)/toolNames

Retrieve the current id and localized name information for all tools enabled for the provided org unit, including restricted tools.

Parameters:
Query Parameters:

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing ToolWithName data blocks for the segment following your bookmark query parameter (or the first segment if the bookmark parameter is missing or empty).

GET /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)/(toolId)

Retrieve the current information for a tool enabled for the provided org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • toolId (D2LID) – Tool ID.

Query Parameters:

  • namesOnly (boolean) – Optional. If true, only tool id and name is returned, and fewer permissions are required.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. If you provide true for the namesOnly query parameter, this action returns a ToolWithName JSON block; otherwise, this action returns an OrgUnitInformation JSON block.

PUT /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)/(toolId)

Update the org unit-level information for a tool.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • toolId (D2LID) – Tool ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an OrgUnitInformation JSON block for the new status of the provided tool.

«  API Properties (versions, logging, authentication)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Configuration variables  »