Creating and Updating faculty relationships via web service

An external vendor may create faculty and attach forms to those relationships over web service. The two related endpoints are relation and faculty_relationship. When a user is added as faculty to a course, a relation entity type is created, which includes fields for faculty role, associated faculty member, and faculty type, which stores the associated faculty_relationship forms. Each assigned faculty_relationship form is a separate entry in the faculty_type field of a relation entity.

Adding a user as faculty via a relation entity

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

Relation entity fields

rid: 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).

// 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);

Success

Successfully created faculty forms return a basic entity object structure, providing the newly created form ID, in the structure below.

(
    [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.

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

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.

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.

// Create empty faculty forms for Conflict of Interest and Disclosure and Speaker Agreement Form
$curl = curl_init("http://yourdomain.com/faculty_relationship.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 faculty forms to store their ids, required for the relation entity
// Create a Conflict of Interest Resolution Form
$coi_form_data = array(
  "type" => 'conflict_of_interest_resolution',
);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($coi_form_data));
$coi_form = json_decode(curl_exec($curl));

// Create a Disclosure and Speaker Agreement Form
$disclosure_speaker_data = array(
  "type" => 'disclosure_and_speaker_agreement',
);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($disclosure_speaker_data));
$disclosure_form = json_decode(curl_exec($curl));

Success

Successfully created faculty forms return a basic entity object structure providing the newly created form ID, in the structure below. These returned form IDs are used when updating the individual form, as well as attaching the form to a faculty relationship, via the field_faculty_type field.

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.

Additional Notes

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:

The corrected structure is as follows: