Course Files¶

FILESYSTEMOBJECTTYPE_T¶

The file system object type:

File System Object Type	Value
Folder	1
File	2

Course.CreateFolder¶

{
    "RelativePath": <string>
}

Course.CreatedFolder¶

{
    "RelativePath": <string>,
    "FolderName": <string>,
    "LastModifiedBy" : <number:D2LID>,
    "LastModifiedDate" : <string:UTCDateTime>
}

Course.FileSystemObject¶

{
    "Name": <string>,
    "FileSystemObjectType": <FILESYSTEMOBJECTTYPE_T>
}

Course.UploadedFile¶

{
    "RelativePath": <string>,
    "FileName": <string>,
    "Size": <integer>,
    "LastModifiedBy" : <number:D2LID>,
    "LastModifiedDate" : <string:UTCDateTime>
}

Copying courses¶

COURSECOMPONENT_T¶

Course offering copy jobs can selectively copy distinct course components. These string labels identify the various course components:

AttendanceRegisters Awards Checklists Competencies Content CourseAppearance CourseFiles Discussions DisplaySettings Dropbox Faq Forms

Glossary Grades GradesSettings Groups Homepages IntelligentAgents LearningOutcomes Links LtiLink LtiTP Navbars

News QuestionLibrary Quizzes ReleaseConditions Rubrics S3Model Schedule SelfAssessments Surveys ToolNames Widgets

Note: The Forms component label indicates registration forms.

COPYJOBSTATUS_T¶

Course offering copy jobs will have one of several distinct states, depending on where they are in the conversion process. These string labels describe the states:

Job state	Description
PENDING	Waiting to be picked up for processing.
PROCESSING	Currently in process.
COMPLETE	Processing finished (may contain processing errors: see Conversion history page for details).
FAILED	Processing halted before finish, owing to errors.
CANCELLED	Job was cancelled before finish.

Course.CreateCopyJobRequest¶

When you make a request for a new course offering copy job, you should provide a JSON structure that looks like this one:

{
    "SourceOrgUnitId": <number:D2LID>,
    "Components": [ <string:COURSECOMPONENT_T>, ... ]|null,
    "CallbackUrl": <string>|null,
    "DaysToOffsetDates": <number:integer>|null,  // Optional, see notes
    "HoursToOffsetDates": <number:decimal>|null,  // Optional, see notes
    "OffsetByStartDateDifference": <boolean>|null  // Optional, see notes
}

Components

JSON array of course component type names, for example "Components": [ "Dropbox", "Grades", "Rubrics" ]. If this array property is present, only the components listed will get copied; if the property is missing or null, then all components will get copied.

CallbackUrl

If you provide a valid URL for this property, when the back-end service completes its copy job, it will issue a POST with the provided URL (including any query parameters you provided) with a CopyJobComplete JSON block in the posted body.

The back-end service expects that your service will respond to that POST with a 200 OK, and respond in a timely fashion (by default, five seconds or less).

DaysToOffsetDates

If you provide a number (max: 5000) here, all the dates copied into your destination course (e.g. due dates, start dates, and end dates on activities such as quizzes) will be offset by the provided number of days. Enter a positive integer to offset forward, and a negative integer to offset backwards.

You cannot use this parameter at the same time as the OffsetByStartDateDifference parameter; doing so will cause a 400 Bad Request error.

HoursToOffsetDates

If you provide a decimal number (less than 24) here, all the dates copied into your destination course (e.g. due dates, start dates, and end dates on activities such as quizzes) will be offset by the provided number of hours. Enter a positive number to offset forward, and negative to offset backwards.

You cannot use this parameter at the same time as the OffsetByStartDateDifference parameter; doing so will cause a 400 Bad Request error.

OffsetByStartDateDifference

When true, the service will find the difference between the start date of the source course (the course that is being copied from) and the start date of the destination course (the course that is being copied to), and offset all the dates copied into the destination course by that difference:

• If the start date of the destination course is earlier than the start date of the source course, the dates will be offset backwards.

• If the start date of the destination course is later than the start date of the source course, the dates will be offset forward.

For example, copying from a course with a course start date of July 1, 2018, at 9:00am into a course with a start date of July 3, 2018, at 8:00am will offset all dates 2 days forward and 1 hour backwards.

You cannot use this parameter at the same time as the DaysToOffsetDates or HoursToOffsetDates parameters; doing so will cause a 400 Bad Request error.

Course.CreateCopyJobResponse¶

When the back-end service creates a new job to copy course offerings, it passes you back this JSON structure containing a job token you can use going forward to check on the status of the ongoing job.

{
    "JobToken": <string>
}

Course.GetCopyJobResponse¶

When you check on the status of an ongoing job to copy course offerings, the back-end service will pass you back a JSON structure like this one containing a status string:

{
    "Status": <string:COPYJOBSTATUS_T>
}

Course.CopyJobComplete¶

When you specify a CallbackUrl property in your original request, the back-end service will POST a structure like this to your callback URL:

{
    "JobToken": <string>,
    "SourceOrgUnitId": <number:D2LID>,
    "TargetOrgUnitId": <number:D2LID>,
    "Status": <string:COPYJOBSTATUS_T>
}

Status

This property will contain either CANCELLED, COMPLETE, or FAILED.

Course.CopyCourseLogMessage¶

{
    "LogId": <number>,
    "CopyCourseJobId": <number:D2LID>,
    "LogDateTime": <string:UTCDateTime>,
    "Message": <string>
}

Importing courses¶

COI_IMPORTJOBSTATUS_T¶

Course offering import jobs will have one of several distinct states, depending on where they are in the import process. These string labels describe the states:

Job state	Description
UPLOADING	Submission of import job to adaptation process.
PROCESSING	Currently in adaptation process for importing.
PROCESSED	Finished adaptation process.
IMPORTING	Currently importing.
IMPORTFAILED	Import failure.
COMPLETED	Import job completed successfully.

COI_IMPORTLOGMESSAGE_T¶

Course offering import job log messages can come in a variety of general forms. We use the term COI_IMPORTLOGMESSAGE_T to stand in for an appropriate identifying integer value.

Import log message type	Value
System	0
Progress	1
Warning	2
Error	3

COI_IMPORTOPERATION_T¶

Course offering import jobs can be created for a number of underlying import operations. We use the term COI_IMPORTOPERATIONTYPE_T to stand in for an appropriate identifying integer value.

Import operation type	Value
Conversion	1
Import	2

Course.GetImportJobResponse¶

When you check on the status of an ongoing job to import a course offering, the back-end service will pass you back a JSON structure like this one containing a status string.

{
    "JobToken": <string>,
    "TargetOrgUnitId": <number:D2LID>,
    "Status": <string:COI_IMPORTJOBTSTATUS_T>
}

When you specify a CallbackUrl parameter on your original import request, the back-end service will post a structure like this to your callback URL, once, when the import job completes (either successfully or unsuccessfully).

Course.ImportCourseLog¶

{
    "LogId": <number:D2LID>,
    "ConversionImportJobId": <number:D2LID>,
    "OperationTypeId": <string:COI_IMPORTOPERATION_T>,
    "LogDateTime": <string:UTCDateTime>,
    "Message": <string>,
    "TypeId": <string:COI_IMPORTLOGMESSAGE_T>
}

Course Templates¶

Course templates provide a way to gather sets of default properties for more efficient course offering creation.

DELETE /d2l/api/lp/(version)/coursetemplates/(orgUnitId)¶

Delete a course template.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to manage or delete courses.

• 404 Not Found – No such org unit, or not a course template.

• 429 Too Many Requests – API call-rate limit exceeded.

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.

Note

Using this action is equivalent to using the route to send an org unit to the recycle bin. You can restore the course template from the recycle bin, if needed.

GET /d2l/api/lp/(version)/coursetemplates/(orgUnitId)¶

Retrieve a course template.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to see course info.

• 404 Not Found – No such org unit, or not a course template.

• 429 Too Many Requests – API call-rate limit exceeded.

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 a CourseTemplate JSON block.

GET /d2l/api/lp/(version)/coursetemplates/schema¶

Retrieve the list of parent org unit type constraints for course offerings built on this template.

Parameters:

• version (D2LVERSION) – API version.

Status Codes:

• 200 OK – Action succeeded.

• 429 Too Many Requests – API call-rate limit exceeded.

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 a JSON array of SchemaElement blocks.

POST /d2l/api/lp/(version)/coursetemplates/¶

Create a new course template.

Parameters:

• version (D2LVERSION) – API version.

JSON Parameters:

• CreateCourseTemplate (Course.CreateCourseTemplate) – New course template properties.

Oauth2 Scopes:

orgunits:coursetemplate:create

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid course template data provided, or could not create new course template.

• 403 Forbidden – No permission to manage or create courses and templates.

• 404 Not Found – Could not resolve org unit for created course template to a known org unit.

• 429 Too Many Requests – API call-rate limit exceeded.

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 a CourseTemplate JSON block containing the data for the new course template.

PUT /d2l/api/lp/(version)/coursetemplates/(orgUnitId)¶

Update the information for a course template.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

JSON Parameters:

• CourseTemplateInfo (Course.CourseTemplateInfo) – Updated course template properties.

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid course template data provided.

• 403 Forbidden – No permission to manage courses.

• 404 Not Found – No such org unit, or not a course template.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This action uses the data in your provided block to completely replace the associated course template’s data on the service.

Course files¶

GET /d2l/api/lp/(version)/(orgUnitId)/managefiles/¶

Retrieve the direct child contents (folders and files) of an org unit path.

Parameters:

• version (D2LVERSION) – API version.

Query Parameters:

• path (string) – Optional. Path relative to the course path, if not specified the course path is used.

Oauth2 Scopes:

managefiles:files:read managefiles:folders:read

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to See the File Listing.

• 404 Not Found – No such path, or no such org unit.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.46+ – Route first appears in LMS v20.24.4.

Return. This action returns a object list page containing the resulting FileSystemObject blocks for the segment specified. The objects are returned folders first followed by files both sorted alphabetically by name. If there are more segments the Next field will be set with the request required for the next segment.

DELETE /d2l/api/lp/(version)/(orgUnitId)/managefiles/file¶

Delete a course file.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

JSON Parameters:

• DeleteFile – Delete file properties.

Query Parameters:

• path (string) – Path to the file to delete relative to the course path.

Oauth2 Scopes:

managefiles:files:manage

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid input data provided.

• 403 Forbidden – No permission to See the File Listing or Delete Files.

• 404 Not Found – Org Unit not found

API Versions:

• 1.44+ – Route first appears in LMS v20.23.7.

DELETE /d2l/api/lp/(version)/(orgUnitId)/managefiles/folder¶

Delete a course folder.

Parameters:

• version (D2LVERSION) – API version.

JSON Parameters:

• DeleteFolder – Delete folder properties.

Query Parameters:

• path (string) – Path to the folder to delete relative to the course path.

Oauth2 Scopes:

managefiles:folders:manage

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid input data provided.

• 403 Forbidden – No permission to See the File Listing or Delete Files.

• 404 Not Found – Org Unit not found

API Versions:

• 1.44+ – Route first appears in LMS v20.23.7.

Note

Delete folder is fully recursive; the back-end service will also delete all sub-folders and files contained wtihin the identified folder.

GET /d2l/api/lp/(version)/(orgUnitId)/managefiles/file¶

Retrieve a course file specified by the path.

Parameters:

• version (D2LVERSION) – API version.

Query Parameters:

• path (string) – Path to the file relative to the course path.

Oauth2 Scopes:

managefiles:files:read

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to see the course file.

• 404 Not Found – No such course file, or no such org unit.

• 429 Too Many Requests – API call-rate limit exceeded.

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 must provide the path query string paramter. It needs to contain a valid path to a file in the current org unit’s content space relative to the org unit’s root path (typically something like /topic1/topic1.html).

Return. This action returns a file stream containing the course file data.

POST /d2l/api/lp/(version)/(orgUnitId)/managefiles/file/save¶

Saves an uploaded course file to specified path.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

Query Parameters:

• overwriteFile (boolean)

Form Parameters:

• fileKey – File key value identifying the uploaded file.

• relativePath – The path relative to the course path where the file will be uploaded.

Oauth2 Scopes:

managefiles:files:manage

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid input data provided.

• 403 Forbidden – No permission to See the File Listing or Upload Files.

• 404 Not Found – Org Unit not found, or RelativePath does not exist.

• 409 Conflict – If the OverwriteFile query parameter is not used or set to false, and a file with the same name already exists in the RelativePath. Conflict - File already exists.

API Versions:

• 1.44+ – Route first appears in LMS v20.23.7.

Input. Provide a POST form with the file key the service sent you from your resumable file upload action. Note that you can provide a name parameter for the framework to use for the file; if you provide no name parameter, the framework seeks to gather the file name from the uploaded file itself.

If you provide a relativePath it should describe the folder path between the established course path and the folder you want to contain your uploaded file; for example temp or temp/upload, or similar.

Note

Before you can use this action to save a course file, the containing folder must exist; if you provide a relative path, then all folders in that relative path must already exist.

Return. This action returns a UploadedFile JSON block for the newly uploaded file.

POST /d2l/api/lp/(version)/(orgUnitId)/managefiles/file/upload¶

Initiate a resumable file upload request for a course file.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

Oauth2 Scopes:

managefiles:files:manage

Status Codes:

• 308 Resume Incomplete – Request to start a resumable upload successfully received and initiated, with response indicating upload path and file key.

• 400 Bad Request – Invalid input data provided.

• 403 Forbidden – No permission to See the File Listing or Upload Files.

• 404 Not Found – Org Unit not found.

API Versions:

• 1.44+ – Route first appears in LMS v20.23.7.

Input. Initiate a resumable upload process. Your POST request must contain three special headers:

• X-Upload-Content-Type to indicate the mime type of the file you’re uploading.

• X-Upload-Content-Length to indicate the total size of the file you’re uploading, in bytes (not the size of the part passed in any individual request).

• X-Upload-File-Name to indicate the file name for the file you’re uploading.

Return. If successful, this action initiates a resumable upload process. As part of that process, the service provides you a file upload path you can use to make further requests to upload parts of your file, and a file key value that you can use to save the uploaded file to the course once you have uploaded the entire content length of your file.

POST /d2l/api/lp/(version)/(orgUnitId)/managefiles/folder¶

Create a folder in course.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

JSON Parameters:

• CreateFolder (Course.CreateFolder) – Create folder properties.

Oauth2 Scopes:

managefiles:folders:manage

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Invalid input data provided.

• 403 Forbidden – No permission to See the File Listing or Create and Edit Files.

• 404 Not Found – Org Unit not found.

API Versions:

• 1.44+ – Route first appears in LMS v20.23.7.

Return. This action returns a CreatedFolder JSON block for the newly created folder.

Copying courses¶

GET /d2l/api/le/(version)/import/(orgUnitId)/copy/(jobToken)¶

Retrieve the status of a queued course copy job request.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID of the target course offering.

• jobToken (string) – Course copy job token.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to retrieve status of copy job.

• 404 Not Found – No such target org unit, no such source org unit (from copy job), no such copy job, or job token is invalid.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.67+ – Route first appears in LMS v20.23.1.

• 1.61-1.66 – Deprecated as of LMS v20.24.1.

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

Return. This action returns a GetCopyJobResponse JSON block.

POST /d2l/api/le/(version)/import/(orgUnitId)/copy/¶

Queue up a new course copy job request.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID of the target course offering.

JSON Parameters:

• CreateCopyJobRequest (Course.CreateCopyJobRequest) – Job request for course copy.

Status Codes:

• 202 Accepted – Job request accepted.

• 400 Bad Request – Source org unit not found, invalid course component string value, invalid (empty) course component list, or invalid combination of date offset parameters.

• 403 Forbidden – No permission to create course copy job request.

• 404 Not Found – Target org unit not found.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.67+ – Route first appears in LMS v20.23.1.

• 1.61-1.66 – Deprecated as of LMS v20.24.1.

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

This action requests the creation of a new course offering copy job to copy one or more course offering components from a source org unit to the target org unit identified in the route path.

Note

The target org unit you provide in the path must exist before you create a copy job.

The job processor in the back-end service will do no check to verify that your request course components have already been copied from the source to the target course.

Return. This action returns a CreateCopyJobResponse JSON block.

GET /d2l/api/le/(version)/ccb/logs¶

Retrieve the list of logs for course copy jobs.

Parameters:

• version (D2LVERSION) – API version.

Query Parameters:

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

• pageSize (number) – Optional. Number of log entries (maximum) to return in each data page (default is 20, maximum is 100).

• sourceOrgUnitId (number) – Optional. Org unit ID from which components where copied.

• destinationOrgUnitId (number) – Optional. Org unit ID to which components where copied.

• startDate – Optional. Fetch logs of course copy jobs started since startDate.

• endDate – Optional. Fetch logs of course copy jobs started before endDate.

Status Codes:

• 200 OK – Action succeeded.

• 400 Bad Request – Provided endDate is early than startDate.

• 403 Forbidden – No permission to retrieve logs of copy course jobs.

• 404 Not Found – No copy course job were found.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• unstable – Route first appears in LMS v10.5.5.

Return. This action returns an object list page containing the resulting CopyCourseLogMessage data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

Importing courses¶

GET /d2l/api/le/(version)/import/(orgUnitId)/imports/(jobToken)¶

Retrieve the status of a queued course import job request.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

• jobToken (string) – Course copy job token.

Oauth2 Scopes:

import:job:fetch

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to retrieve status of import job.

• 404 Not Found – No such target org unit, no such source org unit (from import job), no such import job, or job token is invalid.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.67+ – Route first appears in LMS v20.23.1.

• 1.61-1.66 – Deprecated as of LMS v20.24.1.

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

Return. This action returns a GetImportJobResponse JSON block.

GET /d2l/api/le/(version)/import/(orgUnitid)/imports/(jobToken)/logs/¶

Retrieve the logs for a course import job.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

• jobToken (string) – Course copy job token.

Query Parameters:

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

Status Codes:

• 200 OK – Action succeeded.

• 404 Not Found – No logs found for course import job.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.67+ – Route first appears in LMS v20.23.1.

• 1.61-1.66 – Deprecated as of LMS v20.24.1.

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

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

POST /d2l/api/le/(version)/import/(orgUnitId)/imports/¶

Create a new course import job request.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID of the target course offering.

Query Parameters:

• callbackUrl (string) – Callback URL to post status to.

Oauth2 Scopes:

import:job:create

Status Codes:

• 202 Accepted – Job request accepted.

• 403 Forbidden – No permission to create course import job request.

• 404 Not Found – No such org unit.

• 429 Too Many Requests – API call-rate limit exceeded.

API Versions:

• 1.67+ – Route first appears in LMS v20.23.1.

• 1.61-1.66 – Deprecated as of LMS v20.24.1.

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

Input. Provide the course package to import using the simple file upload process: provide the course package as the upload data to the POST form; set the filename field in the Content-Disposition part-header to the base name of the file you are uploading; set the name field in the part-header to file:

Content-Disposition: form-data; name="file"; filename="ImportPackage.zip"
Content-Type: application/zip

The service will create a new course import job for your course package, and return a job token you can use to query for the job's status.

If you provide a callbackUrl query parameter, it should be a URL that the back-end service can reach, and that you can receive. If you do provide such an URL, then the back-end service will post a GetImportJobStatusResponse JSON block to that URL when the import job completes, successfully or unsuccessfully.

Return. This action returns a simple JSON block containing a token for the import job you can use later to check on the job’s status:

{
   "JobToken": <string>
}