Manipulation of course objects via web services
Course object statuses can be created, and updated, via web services. The entity used to track a user's status in a course object is course_object_fulfillment, which associates a user to a course via the course object id (coid). The course object ID is unique per object, per course, i.e., a webform course object shared between Course A and Course B will have a different coid for each course.
Course object types
The coid can be found via the course_object endpoint, which lists all configured course objects for a given course. The following object_type values may be used to find specific objects from this list. The object_type may also be used as a parameter to query the system directly for a specific object.
Object type machine names
name | object_type | name | object_type | |
|---|---|---|---|---|
Attendance | signup_attendance | Payment | payment | |
Book | book | Poll | poll | |
Certificate | certificate | Quiz | quiz | |
Commitment to Change | ctc | Quiz comparison | comparison | |
Course | course | Quiz self assessment | self_assessment | |
Course page | course_page | SCORM/TinCan | scorm | |
Credit | credit | Warpwire video | warpwire | |
GoToWebinar Video | gotowebinar | Webform | webform | |
link_to_file | Link to file | Zoom video | zoom | |
manual | Manual step |
Discovering a course object id (example query calls)
For example, given the node 123, you may query for a list of all course objects in that course.
http://your-domain.com/course_object.json?nid=123Alternatively, you may query for only specific objects in a course, such as Attendance, with the object_type signup_attendance, or a Manual step with the object_type manual.
http://your-domain.com/course_object.json?nid=123&object_type=signup_attendance
http://your-domain.com/course_object.json?nid=123&object_type=manualThe code examples below use the course object id of 456 for a Manual step object.
Object Workflow
A course object fulfillment record is not created until a user starts an individual object. The most common scenario, needing to update a course object remotely, is configured with two course objects. First, a Course Page object is created, with a link to an external service, which will track, and later update, the user's status. This Course Page object is followed by a Manual course object, which blocks the user's progress until the external service, or admin, has updated their status. In this scenario, the user has paused on the Course Page to click the link, and complete the external page, having never started the Manual course object. As such, the external service will need to send a course object fulfillment creation request, for the Manual course object.
Object scenarios and course_outline_fulfillment return data
There are 3 scenarios for a learner when they interact with a course object.
Learner has not reached the object
Learner has reached the object (viewing it via the outline) and has NOT met criteria to proceed forward
Learner has completed all criteria for the object.
A learner's completion status may be set automatically by the object (getting a passing grade on a quiz), or manually by an admin (more common in Attendance or Manual step objects).
The results in the object fulfillment return would be
Learner has NO course_object_fulfillment record present in the result set
Learner has course_object_fulfillment record with complete set to 0
Learner has course_object_fulfillment record with complete set to 1
Creating a course object fulfillment record
POST course_object_fulfillment.json
{
"coid": 456, // The course object ID
"uid": 200, // User ID
"grade_result": 60, // The object grade, when applicable. Used for reporting. It does not affect complete status.
"date_started": 1461613186,
"complete": 0 // This marks the object as incomplete. A setting of 1 allows the user to navigate to the next object immediately
}
A successful update will return the entity "id", which is the course object fulfillment id (cofid) used in any future update calls. For instance, the call above created an object with the cofid of 1000, as seen in the return array below.
Updating a course object fulfillment record
In the call above, the user did not pass the object immediately. They were marked as incomplete, and unable to proceed past the Manual object. In the next call, we will update the same record with a passing grade, recent date, and a completed status, to allow the user to continue past the object.
PUT course_object_fulfillment/1000.json
A successful update call will return an empty array as a the body, with an HTTP Status Code of 200 OK.
For an explanation of the information returned from web service requests, see Web Service Responses.
How do I find the course object fulfillment record of an object a user has started?
If a user has already started an object that requires an update from an external service, you can use the web service, along with the user id (uid) and course object id (coid), to find the cofid.
It is recommended to run this check before any creation requests, to prevent errors by attempting to create a record that already exists in the system.
GET course_object_fulfillment.json?uid=200&coid=1000