Valence (September 2014)

Courses (course offerings, templates, schemas)

«  Calendar (Events and scheduling)   ·  [   home  ·   forums  ·   reference   ·  index   ·  routing table   ·  modules   ]   ·  Course competencies and objectives  »

Contents

With the courses resource you can retrieve information about existing courses, modify or remove them, and create new courses.

Attributes

Note that frequently the course-related JSON data blocks include a Path property – these contain a path to the course content published in the service’s content store.

Course.BasicOrgUnit

This composite contains basic information about an organizational unit to which a course offering is related.

{
    "Identifier": <string:D2LID>,
    "Name": <string>,
    "Code": <string>
}
Course.CourseOffering

The service’s fundamental information block for course offerings. Notice that the last few fields for this block include BasicOrgUnit blocks for the related org units.

{
    "Identifier": <string:D2LID>,
    "Name": <string>,
    "Code": <string>,
    "IsActive": <boolean>,
    "Path": <string>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "CourseTemplate": { <composite:Course.BasicOrgUnit> }|null,
    "Semester": { <composite:Course.BasicOrgUnit> }|null,
    "Department": { <composite:Course.BasicOrgUnit> }|null
}
Course.CourseOfferingInfo

When you use actions that update course information for a course offering, you should provide one of these blocks:

{
    "Name": <string>,
    "Code": <string>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "IsActive": <boolean>
}
Course.CreateCourseOffering

Block used to create a course.

{
    "Name": <string>,
    "Code": <string>,
    "Path": <string>,
    "CourseTemplateId": <number:D2LID>,
    "SemesterId": <number:D2LID>|null,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "LocaleId": <number:D2LID>|null,
    "ForceLocale": <boolean>,
    "ShowAddressBook": <boolean>
}
ForceLocale
Determines if the course should override the user’s saved locale preference.
Path
The root path to use for this course offering’s course content. Note that, if your back-end service has path enforcement set on for new org units, then you should leave this property as an empty string, and the back-end service can populate it for you.
SemesterId
Note that if CreateCourse form does not include the Semester element, then you should provide null for this property when creating a course.
ShowAddressBook
Determines if the email tool’s address book groups together the users enrolled in the course together.
Course.CourseTemplate
{
    "Identifier": <string:D2LID>,
    "Code": <string>,
    "Name": <string>,
    "Path": <string>
}
Course.CourseTemplateInfo
{
    "Name": <string>,
    "Code": <string>
}
Course.CreateCourseTemplate
{
    "Name": <string>,
    "Code": <string>,
    "Path": <string>,
    "ParentOrgUnitIds": [ <number:D2LID>, ... ]
}
Path
The root path to use for this course template’s course content. Note that, if your back-end service has path enforcement set on for new org units, then you should leave this property as an empty string, and the back-end service can populate it for you.
Course.SchemaElement

This block describes constraints for parent org units of course offerings (that is, whether particular org units are not permitted as parents for course offerings, or are required as parents for course offerings).

{
    "Type": { <composite:OrgUnit.OrgUnitTypeInfo> },
    "IsNotAllowed": <boolean>,
    "IsRequired": <boolean>
}
Type
OrgUnit.OrgUnitTypeInfo composite block to describe the org unit type for a course schema.
IsNotAllowed
If true, the org unit type cannot be a parent to the org unit.
IsRequired
If true, the org unit type is required as a parent to the org unit. This value takes precedence over the IsNotAllowed property’s value.

Copying courses

COURSECOMPONENT_T

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

  • AttendanceRegisters
  • Classlists
  • Checklists
  • Competencies
  • Content
  • CourseFiles
  • Discussions
  • DisplaySettings
  • Dropbox
  • Faq
  • Forms
  • Glossary
  • Grades
  • GradesSettings
  • Groups
  • Homepages
  • IntelligentAgents
  • Links
  • LtiLink
  • LtiTP
  • Navbars
  • News
  • QuestionLibrary
  • Quizzes
  • ReleaseConditions
  • Rubrics
  • Schedule
  • SelfAssessments
  • Surveys
  • ToolNames
  • Widgets
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
}
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 copies.
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).

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.

Importing courses

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.
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: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.CreateImportJobResponse
{
    "JobToken": <string>
}

Actions

DELETE /d2l/api/lp/(version)/courses/(orgUnitId)

Delete a course offering.

Parameters:
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
GET /d2l/api/lp/(version)/courses/schema

Retrieve the list of parent org unit type constraints for course offerings.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of SchemaElement blocks.

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

Retrieve a course offering.

Parameters:
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a CourseOffering JSON block with the provided course’s information.

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

Create a new course offering.

Parameters:
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid course data provided, or could not create new course.
  • 403 Forbidden – No permission to manage or create courses.
  • 404 Not Found – Could not resolve org unit for created course to a known org unit.
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a CourseOffering JSON block for the newly created course.

PUT /d2l/api/lp/(version)/courses/(orgUnitId)

Update a current course offering.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Input. This action replaces the associated course offering’s data with all the properties you provide.

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:
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
GET /d2l/api/lp/(version)/coursetemplates/(orgUnitId)

Retrieve a course template.

Parameters:
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

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:
Status Codes:
  • 200 OK – Action succeeded.
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of SchemaElement blocks.

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

Create a new course template.

Parameters:
JSON Parameters:
 
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.
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
PUT /d2l/api/lp/(version)/coursetemplates/(orgUnitId)

Update the information for a course template.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.1Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Input. This action uses the data in your provided block to completely replace the associated course template’s data on the service.

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.
  • 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.
API Versions:
  • 1.5+ – Route first appears in Learning Environment v10.4.0.

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:
 
Status Codes:
  • 202 Accepted – Job request accepted.
  • 400 Bad Request – Source org unit not found, invalid course component string value, or invalid (empty) course component list.
  • 403 Forbidden – No permission to create course copy job request.
  • 404 Not Found – Target org unit not found.
API Versions:
  • 1.5+ – Route first appears in Learning Environment v10.4.0.

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.

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.
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.
API Versions:
  • unstable – Route first appears in Learning Environment v10.4.3.

Return. This action returns a GetImportJobResponse JSON block.

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.
Status Codes:
API Versions:
  • unstable – Route first appears in Learning Environment v10.4.3.

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, and set the name field in the Content-Disposition part-header to “file”.

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 CreateImportJobResponse JSON block.


«  Calendar (Events and scheduling)   ·  [   home  ·   forums  ·   reference   ·  index   ·  routing table   ·  modules   ]   ·  Course competencies and objectives  »