In EthosCE most content is a node. This includes, but is not limited to, site pages, series, sessions and courses. All web service calls to create these pieces of content go to though the node endpoint. Additionally, all fields, including custom fields, can be sent via web service, in creation and update calls. The following structure applies to any course type in the system, with the appropriate changes to field names.
The course type may be updated by changing the type value of the data array sent.
Internal Value | |
|---|---|
Course | course |
Session | group_event_series_event |
Most content types in Ethos use the body field for the main content, except Courses, which use the field_course_summary field, referenced below.
NOTE: When creating or updating an entity
For any call, you must specify the format being posted in a Content-Type HTTP header, either "application/json" or "text/xml".
Creating a course
The PHP/Curl script below creates a course with the following details:
A live event, on Aug 20 2018, from 9am to 5pm EST, open from Aug 20 2017 to Aug 20 2018.
The course awards 2 credit types, 1.00 Attendance credit, and 1.00 - 5.50 variable AMA credits, in .25 increments.
It includes information on the venue, it's location, website, phone number, and travel information.
The SKU number is DLC_1234, and the price is $100.
After creating the course we record the new nid sent by the system, and use it to assign the 2 credit types.
Creating a course
<?php
$domain = 'your-domain.com';
$userpass = 'restws_webservice:restws_webservice';
// Build a course to send, in JSON.
$course = array(
'title' => 'My Course', // A single line textbox
'type' => 'course',
'field_course_summary' => array( // A multi-line text area field
'value' => 'A <b>summary</b> of the course',
'format' => 'full_html'
),
'author' => 1, // It is best practice is to assign the Web Service user id as author
'status' => 1, // Status (published): A single select checkbox. Either 1 or 0
'field_course_date' => array(
'value' => '2017-08-20T13:00:00',
'value2' => '2018-08-20T21:00:00',
),
'field_course_event_date' => array(
'value' => '2018-08-20T13:00:00',
'value2' => '2018-08-20T21:00:00',
),
'sell_price' => 100.00,
'model' => 'DLC_1234',
'field_learning_objectives' => array(
'value' => '<p>Objectives for learning.</p>',
'format' => 'full_html'
),
'field_hotel_travel' => array(
'value' => '<p>Attendees will have a block of rooms available at <b>The Double Tree</b></p>',
'format' => 'full_html'
),
'field_hotel_information' => array(
'value' => '<p>Please call the front desk for rates.</p>',
'format' => 'full_html'
),
"field_hotel_link" => array(
"title" => "Venue Website",
"url" => "doubletree3.hilton.com",
),
'field_venue_phone' => array(
'number' => '2158931600',
'country_code' => 'us' // Link to list
),
"field_course_location" => array(
"name" => "Double Tree Philadelphia",
"street" => "237 S Broad Street",
"additional" => "",
"city" => "Philadelphia",
"province" => "PA",
"postal_code" => "19107",
"country" => "us",
),
"field_course_live" => 1, // The 'Live' checkbox, under Course settings must be checked for live events
"field_course_category" => array( // Course Category is field containing a list of taxonomy terms. The id values entered here are the integer term ids
array('id' => 50),
array('id' => 60),
),
"field_course_format" => array(
array('id' => 10),
array('id' => 20),
),
);
$json = json_encode($course);
$curl = curl_init('http://' . $domain . '/node.json');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $userpass); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
// Send the course creation request
$http_return = curl_exec($curl);
$response = json_decode($http_return);
print_r($response);
/*
An example response, returned in JSON:
(
[uri] => http://your-domain.com/node/408
[id] => 408
[resource] => node
[uuid] => f88adca4-8332-459c-873f-1bad3724b13e
)
*/
// Get the nid to send credit information
$nid = $response->id;
// Add Credit
$curl = curl_init('http://' . $domain . '/course_credit.json');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $userpass); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
// Enable Attendance
$credit_attendance = array(
'nid' => $nid,
'active' => 1,
'type' => 'attendance',
"increments" => 0,
"min" => 0,
"max" => 1,
"enable_variable_credit" => 0,
);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($credit_attendance));
$http_return = curl_exec($curl);
$response = json_decode($http_return);
print_r($response);
// Enable AMA
$credit_ama = array(
'nid' => $nid,
'active' => 1,
'type' => 'ama',
"increments" => 0.25,
"min" => 1.,
"max" => 5.5,
"enable_variable_credit" => 1,
);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($credit_ama));
$http_return = curl_exec($curl);
$response = json_decode($http_return);
print_r($response);
Updating a course's title
When updating any content, the payload sent is trimmed down to only the fields being updated. To update the course created in the previous section, we use the URI sent, http://your-domain.com/node/408.
Note the usage of "PUT" instead of "POST"
Updating a course's title
<?php
// Build a course
// The fields and allowed values are available on the full documentation site.
$course = array(
'title' => 'My Updated Course',
);
$json = json_encode($course);
$curl = curl_init('http://your-domain.com/node/408');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
$response = curl_exec($curl);
print $response;
Updating a course's external ID
After creating a course via web service, clients may need to update the External course ID field, with a value associated to the external system. This update call is different than the title, detailed above. The title field is attached to the node entity, however the External course ID field is attached to the course entity, a separate collection of data. It is used for primarily for internal purposes, and is seldom changed manually. However, in this case of a course created externally via web service, there may be a need to associate the new course with an external system ID.
To update the course created in the previous section, we take the nid returned, above example is 408, and send a PUT call, via the course endpoint, to updated the External course ID field. The internal name of the field is external_id.
Warning
It is not recommended to update any other fields found in the course endpoint, except external_id, as they are programatically created/updated when editing a course via the UI.
Updating a course's external ID
<?php
// Build a course
// The fields and allowed values are available on the full documentation site.
$course = array(
'external_id' => 'ethosce_ext_id_12345',
);
$json = json_encode($course);
$curl = curl_init('http://your-domain.com/course/408');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
$response = curl_exec($curl);
print $response;