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

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=123

Alternatively, 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=manual

The 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.

Creating a course object fulfillment record

<?php
// Send the creation request
$object_info = array(
  "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
);
$curl = curl_init("http://your-domain.com/course_object_fulfillment");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($object_info));

$json = curl_exec($curl);

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.

{"uri":"http://your-domain.com/course_object_fulfillment/1000","id":"1000","resource":"course_object_fulfillment","uuid":"d955ee03-0161-4778-9872-7f229b57bad4"}

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.

<?php
// Send the update request, via PUT
// Only the attributes being updated need to be sent
$object_info = array(
  "grade_result" => 90, // The updated grade
  "date_started" => 1461610021, // The updated date
  "date_completed" => 1461610021, // The completion date
  "complete" => 1, // Mark the object as complete.
);
// Note the course object fulfillment id (cofid) in the URL, for updating
$curl = curl_init("http://your-domain.com/course_object_fulfillment/456.json"); 
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($object_info));

$json = curl_exec($curl);

A successful update call will return an empty array as a the body, with an HTTP Status Code of 200 OK.

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.

<?php
// Send a get request to find the cofid
$curl = curl_init("http://your-domain.com/course_object_fulfillment.json?uid=200&coid=456"); 
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);

$json = curl_exec($curl);
$response = json_decode($json);

if(!empty($response)){
  $cofid = $response['id']; // The entity id of the course object fulfillment record is the cofid
  // Update the found course object fulfillment record
}else{
  // Create a new course object fulfillment record
}