Valence (May 2014)

Courses (course offerings, templates, schemas)

«  Calendar (Events and scheduling)   ·  [   home  ·   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
  • LtiLinks
  • LtiTP
  • Navbars
  • News
  • 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.

Actions

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

Delete a course offering.

Parameters:
Status Codes:
  • 200 – Action succeeded.
  • 403 – No permission to manage or delete courses.
  • 404 – Org unit not found or not a course offering.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.0.
GET /d2l/api/lp/(version)/courses/schema

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

Parameters:
Status Codes:
  • 200 – Action succeeded.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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:
  • 200 – Action succeeded.
  • 403 – No permission to see course offerings.
  • 404 – Org unit not found or not a course offering.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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 – Action succeeded.
  • 400 – Invalid course data provided, or could not create new course.
  • 403 – No permission to manage or create courses.
  • 404 – Could not resolve org unit for created course to a known org unit.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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:
  • 200 – Action succeeded.
  • 400 – Invalid course data provided.
  • 403 – No permission to update courses.
  • 404 – Org unit not found or not a course offering.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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:
  • 200 – Action succeeded.
  • 403 – No permission to manage or delete courses.
  • 404 – No such org unit, or not a course template.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.0.
GET /d2l/api/lp/(version)/coursetemplates/(orgUnitId)

Retrieve a course template.

Parameters:
Status Codes:
  • 200 – Action succeeded.
  • 403 – No permission to see course info.
  • 404 – No such org unit, or not a course template.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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 – Action succeeded.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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 – Action succeeded.
  • 400 – Invalid course template data provided, or could not create new course template.
  • 403 – No permission to manage or create courses and templates.
  • 404 – Could not resolve org unit for created course template to a known org unit.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.0.
PUT /d2l/api/lp/(version)/coursetemplates/(orgUnitId)

Update the information for a course template.

Parameters:
JSON Parameters:
 
Status Codes:
  • 200 – Action succeeded.
  • 400 – Invalid course template data provided.
  • 403 – No permission to manage courses.
  • 404 – No such org unit, or not a course template.
API Versions:
  • 1.0Deprecated as of LMS v10.3.0.
  • 1.1+ – Route first appears in LMS v10.0.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 – Action succeeded.
  • 403 – No permission to retrieve status of copy job.
  • 404 – 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 LMS 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 – Job request accepted.
  • 400 – Source org unit not found, invalid course component string value, or invalid (empty) course component list.
  • 403 – No permission to create course copy job request.
  • 404 – Target org unit not found.
API Versions:
  • 1.5+ – Route first appears in LMS 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.


comments powered by Disqus

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