Developer Platform (May 2017)

Organization structure (Org units, structure)

«  Enrollments (groups, sections, auditors)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Discussions (forums, topics, posts)  »

Contents

These actions and structures provide access to the organization structure configured for an LMS. The structure is grouped into generic nodes called org units (organizational units). An org unit node can represent several different kinds of things within an LMS and the institution determines the precise mixture of custom org unit types available through its LMS. However, by default, an LMS comes with several built-in org unit types (course offerings, departments, semesters) fundamental to most learning institutions.

Attributes

Org.Organization

Fundamental information for the organization itself (the root org unit).

{
    "Identifier": <string:D2LID>,
    "Name": <string>
}

Org units

OrgUnitEditor.ColourScheme
{
    "Dark": <string>,
    "Light": <string>,
    "Soft": <string>
}
OrgUnit.OrgUnit

Fundamental information for an org unit as reported by org unit service actions.

{
    "Identifier": <string:D2LID>,
    "Name": <string>,
    "Code": <string>|null,
    "Type": { <composite:OrgUnit.OrgUnitTypeInfo> }
}
Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only.
OrgUnit.OrgUnitProperties
{
    "Identifier": <string:D2LID>,
    "Name": <string>,
    "Code": <string>|null,
    "Path": <string>,
    "Type": { <composite:OrgUnit.OrgUnitTypeInfo> }
}
Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only. You may never provide null when setting the code for an org unit.

Note

Note that only the Name, Code, and Path values are used by the back-end service on update actions.

OrgUnit.OrgUnitCoreInfo

Encapsulates the core information associated with an org unit for use by other services (for example, the Dropbox related actions).

{
    "Identifier": <string:D2LID>,
    "TypeIdentifier": <string>,
    "Name": <string>,
    "Code": <string>|null,
    "Path": <string>,
    "IsActive": <boolean>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null
}
Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only.
OrgUnit.OrgUnitCreateData

Actions that create or update custom org units should provide data to the service in blocks that look like this:

{
    "Type": <number:D2LID>,
    "Name": <string>,
    "Code": <string>,
    "Parents": [ <number:D2LID>, ... ]
}
Code

Note that org unit code values have these limitations:

  • They cannot be more than 50 characters in length.

  • They may not contain these special characters:

    \ : * ? “ ” < > | ‘  # , % &
    
Type
D2LID for the org unit’s associated org unit type.
Parents
JSON array of Org unit IDs that identify this org unit’s immediate parent org units.

Org unit types

OrgUnit.OrgUnitType

Actions that retrieve Org Unit Type information from the service receive blocks that look like this:

{
    "Id": <number:D2LID>,
    "Code": <string>,
    "Name": <string>,
    "Description": <string>,
    "SortOrder": <number>,
    "Permissions": { <composite:OrgUnit.Permissions> }
}
OrgUnit.Permissions
{
    "CanDelete": <boolean>,
    "CanEdit": <boolean>
}
OrgUnit.CreateOrgUnitTypeData

Actions that create or update custom org unit types should provide data to the service in blocks that look like this:

{
    "Code": <string>,
    "Name": <string>,
    "Description": <string>,
    "SortOrder": <number>
}
OrgUnit.OrgUnitTypeInfo

Encapsulates the core information associated with an org unit type for use by other services (for example, the Enrollment and Course related actions).

{
    "Id": <number:D2LID>,
    "Code": <string>,
    "Name": <string>
}

Actions

GET /d2l/api/lp/(version)/organization/info

Retrieve the organization properties information.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
  • 404 Not Found – This organization hasn’t set its identifier and name.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a Organization JSON data block containing the identifier and name of the organization.

Structure

DELETE /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/(childOrgUnitId)

Delete the relationship between a provided org unit and one of its children.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • childOrgUnitId (D2LID) – Org unit ID for the child to detach.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
DELETE /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/(parentOrgUnitId)

Delete the relationship between a provided org unit and one of its parents.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • parentOrgUnitId (D2LID) – Org unit ID for the parent to detach.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
GET /d2l/api/lp/(version)/orgstructure/

Retrieve properties for all org units.

Parameters:
Query Parameters:
 
  • orgUnitType (string) – Optional. Filter to org units with type matching this org unit type ID.
  • orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
  • orgUnitName (string) – Optional. Filter to org units with names containing this substring.
  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves. Note that for orgUnitType, the back-end service expects to receive a valid org unit type ID value.

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

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)

Retrieve the properties for a provided org unit.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a OrgUnit JSON structure containing the properties for the provided org unit.

GET /d2l/api/lp/(version)/orgstructure/childless/

Retrieve all org units that have no children.

Parameters:
Query Parameters:
 
  • orgUnitType (string) – Optional. Filter to org units of this type.
  • orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
  • orgUnitName (string) – Optional. Filter to org units with names containing this substring.
  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to search for childless org units.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves.

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

GET /d2l/api/lp/(version)/orgstructure/orphans/

Retrieve all org units that are orphans (have no parents).

Parameters:
Query Parameters:
 
  • orgUnitType (string) – Optional. Filter to org units of this type.
  • orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
  • orgUnitName (string) – Optional. Filter to org units with names containing this substring.
  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to search for orphaned org units.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves.

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

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/ancestors/

Retrieve a list of ancestor-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId – Optional. Filter retrieved list by this org unit type.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of OrgUnit data blocks containing information about all the org units that are ancestors of the provided org unit.

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/

Retrieve a list of child-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of OrgUnit data blocks containing information about all the org units that are children of the provided org unit.

Warning

An organization structure can grow to be a very large collection of nodes. We advise that you make very careful use of this API call because it asks for an unbounded set of results. We strongly recommend you use the paged version of this call instead.

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/paged/

Retrieve a list of child-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/descendants/

Retrieve a list of descendent-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of OrgUnit data blocks containing information about all the org units that are descendants of the provided org unit.

Warning

An organization structure can grow to be a very large collection of nodes. We advise that you make very careful use of this API call because it asks for an unbounded set of results. We strongly recommend you use the paged version of this call instead.

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/descendants/paged/

Retrieve a list of descendent-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/

Retrieve a list of parent-units for a provided org unit.

Parameters:
Query Parameters:
 
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of OrgUnit data blocks containing information about all the org units that are parents of the provided org unit.

POST /d2l/api/lp/(version)/orgstructure/

Create a new custom org unit.

Parameters:
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid org structure creation data provided, or creation of specified org unit type not permitted in the called context, or specified parent org unit not allowed for specified org unit type.
  • 403 Forbidden – No permission to edit organizational structure.
  • 404 Not Found – Org unit not found.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns an OrgUnit JSON data block containing the properties for the newly created org unit.

POST /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/

Give the provided org unit a new child org unit.

Parameters:
JSON Parameters:
 
  • OrgUnitId (D2LID as single JSON number) – Org unit to add as a child.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to add org unit with ID 1234 as a child of another org unit, your POST body would be:

1234
POST /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/

Give the provided org unit a new parent org unit.

Parameters:
JSON Parameters:
 
  • OrgUnitId (D2LID as single JSON number) – Org unit to add as a parent.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to add org unit with ID 1234 as a parent of another org unit, your POST body would be:

1234
PUT /d2l/api/lp/(version)/orgstructure/(orgUnitId)

Update a custom org unit’s properties

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit to update.
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Input. Note that you can only update the Name, Code, and Path properties; the values of the other proprties in the OrgUnitProperties you provide are not used to update your specified org unit.

Return. This action returns an OrgUnitProperties JSON data block containing the properties for the newly created org unit.

Colour schemes

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours

Retrieve the colour scheme for an org unit.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to view the colour scheme.
  • 404 Not Found – Org unit not found, or colour scheme for org unit not found.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Return. This action returns a ColourScheme JSON data block containing the org unit’s current colour scheme.

PUT /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours

Set a new colour scheme for an org unit.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Return. This action returns a ColourScheme JSON data block containing the org unit’s new colour scheme.

Recycle bin

DELETE /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)

Permanently delete an org unit from the recycle bin.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.
GET /d2l/api/lp/(version)/orgstructure/recyclebin/

Retrieve all the org units currently in the recycle bin.

Parameters:
Query Parameters:
 
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

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

POST /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)/recycle

Send an org unit to the recycle bin.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.
POST /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)/restore

Restore an org unit from the recycle bin.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4Obsolete as of LMS v10.7.0.

Types

DELETE /d2l/api/lp/(version)/outypes/(orgUnitTypeId)

Delete a particular org unit type.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitTypeId (D2LID) – Org unit type ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Unable to delete org unit type at this time (a service component depends upon it).
  • 403 Forbidden – No permission to delete org unit types, or attempt to delete built-in org unit type
  • 404 Not Found – Org unit type not found.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
GET /d2l/api/lp/(version)/outypes/

Retrieve all the known and visible org unit types.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of OrgUnitType JSON data blocks containing information for all the known and visible org unit types. This action will not provide any of the not-visible org unit types.

GET /d2l/api/lp/(version)/outypes/(orgUnitTypeId)

Retrieve information about a particular org unit type.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitTypeId (D2LID) – Org unit type ID.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
GET /d2l/api/lp/(version)/outypes/department

Retrieve the org unit type information for department org units.

Parameters:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a OrgUnitType JSON data block containing the properties of the built-in department org unit type.

GET /d2l/api/lp/(version)/outypes/semester

Retrieve the org unit type information for semester org units.

Parameters:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a OrgUnitType JSON data block containing the properties of the built-in semester org unit type.

POST /d2l/api/lp/(version)/outypes/

Create a new custom org unit type.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a OrgUnitType JSON data block containing the current properties for the new custom org unit type.

POST /d2l/api/lp/(version)/outypes/(orgUnitTypeId)

Update a particular org unit type.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitTypeId (D2LID) – Org unit type ID.
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a OrgUnitType JSON data block containing the current, updated properties for the custom org unit type.

«  Enrollments (groups, sections, auditors)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Discussions (forums, topics, posts)  »