...
To assign an existing user in the system as faculty in a course, the user id (uid) and course id (nid) are required. If faculty forms are to be assigned, their individual form IDs must also be available. The endpoint field supports values, both arrays, using the resource key to designate the entity type (source course node or target user).
| Info | |
|---|---|
| title | Relation entity fieldsrid: The relation identifier. An internal value. relation_type: The bundle type of the relation entity itself. This is always 'faculty' field_published: A boolean controlling whether the faculty information displays on the course landing page. Defaults to 0 (unpublished) field_faculty_role: An array of term ids (tid) from the Faculty Role taxonomy. field_faculty_type: An array of entity ids of each form assigned to the user relationship endpoints: The relationship between user and course. A multidimensional array, storing the two entities to be connected, a course node and user account. When viewing a GET call of a relation entity, you will also see two related fields, endpoints_source_node and endpoints_target_user are dynamically created from the endpoints field, when viewing the relation and cannot be manipulated directly. |
Example
In this example a PHP/cURL script will add an existing user (uid 750) to a course with nid 50, with the roles Planner (id 44) and Speaker (id 46).
| Code Block |
|---|
// Global settings
$curl = curl_init("http://yourdomain.com/relation.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"));
// Create the Relation entity for an existing user
$relation = array(
"relation_type" => 'faculty',
// Taxonomy term ids
"field_faculty_role" => array(
array('id' => 44),
array('id' => 46),
),
// The account and course references. NOTE: The multidimensional array structure
"endpoints" => array(
array('id' => 50, 'resource' => 'node'),
array('id' => 750, 'resource' => 'user'),
),
);
// Send call
$response = curl_exec($curl); |
...
Successfully created faculty forms return a basic entity object structure, providing the newly created form ID, in the structure below.
| Code Block |
|---|
(
[uri] => http://yourdomain.com/relation/10
[id] => 10
[resource] => relation
) |
Creating a faculty_relationship form
Faculty forms are created and updated with the same structure as any other field enabled data point in the system, such as course nodes or user profiles, which support text fields, select boxes, and taxonomy fields, among others. The only required field is type which is the bundle machine name of the faculty relationship type.
| Info |
|---|
A faculty_relationship form, or forms, are not required when creating or updating a faculty relationship via web service. A user may be assigned as faculty without a form. |
EthosCE provides the following default forms
Machine name | Bundle |
|---|---|
conflict_of_interest_resolution | Conflict of Interest Resolution Form |
disclosure_and_speaker_agreement | Disclosure and Speaker Agreement Form |
disclosure_form | Disclosure Form |
presentation_request_form | Presentation request form |
speaker_agreement_form | Speaker Agreement Form |
Example
In the examples below we use the faculty_relationship endpoint to create two forms for a user to complete, Conflict of Interest and Disclosure. We then attach the forms to the relationship, via the relation endpoint.
| Info | |
|---|---|
| false | The user and course node identifiers, uid and nid, are NOT sent in this call. That data is associated to the form via the relationship itself, controlled by the relation entity, created separately. |
...
| Code Block |
|---|
# Conflict of Interest form
(
[uri] => http://yourdomain.com/faculty_relationship/30
[id] => 30
[resource] => faculty_relationship
)
# Disclosure and Speaker Agreement Form
(
[uri] => http://yourdomain.com/faculty_relationship/31
[id] => 31
[resource] => faculty_relationship
) |
Attaching a faculty form to a relationship
You can attach created faculty forms to a relationship via the field_faculty_type field. Update calls to entities in the web service only require the fields to be updated in the call.
| Code Block |
|---|
// Global settings
$curl = curl_init("http://yourdomain.com/relation/10");
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "username:password"); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
$relation = array(
'field_faculty_type' => array(
array('id' => 31),
),
);
// Send call
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($relation));
$response = json_decode(curl_exec($curl)); |
Additional Notes
| Info | icon | false
|---|---|
| title | Adding anonymous users as facultyAnonymous relationships, containing e-mails not attached to an existing user, are unsupported via web services. The suggested approach is to create a user via web service, and create the relationship as described above. |
| Warning |
|---|
...
406 Not Acceptable: The faculty relation type does not allow user entities as source |
The endpoint item with the resource type of node must always be first in the endpoint array data structure, to indicate it as a the source. In example the following JSON payload is incorrect:
| Code Block |
|---|
"endpoints":[ // Here the user data is first, which will result in anerror message { error message { "id":781, "resource":"user", "r_index":1 },{ { "id":52, "resource":"node", "r_index":0 } ] |
The corrected structure is as follows:
| Code Block |
|---|
"endpoints":[{ { "id":52, "resource":"node", "r_index":0 },
{
"id":781, "resource":"user", "r_index":1} } ] |