Adding and Modifying Employees

Matching Fields

Native WordPress Fields

• title => First Name Last Name (samaccountname)
• ID => A unique ID generated and used by WordPress (will not be present in Banner data, but will be necessary in order to update an existing employee)
• status => This should always be set to publish and does not correspond to any Banner/Active Directory fields

Custom Meta Fields

• employee_first-name => First Name
• employee_last-name => Last Name
• employee_title => Job Title
• employee_email => UMW Email Address
• employee_phone => UMW Phone Number (formatted as (###) ###-####)
• employee_office-room-number => UMW Office Number
• employee_username => Banner Username/SAMAccountName
• employee_building => The WordPress ID of the building in which this employee's main office is located

These are all of the standard fields that you will be able to update for employees. Their employee/department relationships are a bit more complex, and are outlined in other sections of this documentation.

Updating Employee Information

To update any of the information listed above, you will need to make an authenticated PUT or POST request to the REST API.

For purposes of this document, we are not manipulating the employee_building field yet, as that will require a separate query to retrieve the WordPress ID of the building, first.

In both situations described below, when updating an existing employee, you will need the employee's WordPress post ID, so you may need to retrieve the employee by different means (for instance, retrieve the employee by their username) in order to obtain the ID of that employee entry.

The URL structure to update an existing employee is /wp-json/wp/v2/employee/<id>. For instance, to update the employee with a WordPress ID of 1234 on the staging version of the employee directory, you would send a PUT or POST request to http://umwwebmaster.staging.wpengine.com/directory/wp-json/wp/v2/employee/1234.

This URL is only useful for updating the employee's display name (in the format of [First Name] [Last Name] ([samaccountname]) e.g. Curtiss Grymala (cgrymala)).

Your PUT or POST request should include the information that you want to update. For instance, to send a request using WordPress PHP to update the employee with an ID of 2162, you would use some code similar to the following:

<?php
$url = 'http://umwwebmaster.staging.wpengine.com/directory/wp-json/wp/v2/employee/2162';
/**
 * Build out the body of the request as an associative array with 
 * 		the field names as the keys, and the field values as the
 * 		array values.
 */
$body = array(
	'ID'                  => 2162, 
	'title'               => 'New Employee (nemploye)', 
	'status'              => 'publish', 
	'employee_username'   => 'nemploye', 
	'employee_first-name' => 'New', 
	'employee_last-name'  => 'Employee', 
	'employee_title'      => 'API Tester', 
	'employee_email'      => 'nemploye@umw.edu', 
	'employee_phone'      => '(123) 456-7890', 
	'employee_office-room-number' => 'Room 1408', 
);
/**
 * Set the necessary headers for the API request. In this case, the 
 * 		only header necessary is the Authorization header. That should 
 * 		be a base64 encoded string that concatenates the username and 
 * 		the password with a colon between the two.
 */
$headers = array(
    'Authorization' => 'Basic ' . base64_encode( UMW_ALERTS_USER_NAME . ':' . UMW_ALERTS_USER_PWD ), 
);
/**
 * Set up the request arguments, including the method, necessary 
 * 		headers, and the body of the request
 */
$args = array( 
    'method' => 'PUT', 
    'headers' => $headers, 
    'body' => http_build_query( $body ) 
);
/**
 * Perform the PUT request
 */
$done = wp_remote_request( $url, $args );
/**
 * Store the returned value (a JSON object) in case we need it 
 * 		for use later in the process
 */
$result = @json_decode( wp_remote_retrieve_body( $done ) );

The example above uses the following native PHP and WordPress functions:

• http_build_query() - processes the body array and returns it as a URL-encoded string to be sent through the request.
• base64_encode() - necessary to encode the Basic Auth username/password information.
• wp_remote_request() - performs the actual PUT/POST request. This is a wrapper function in WordPress that attempts to utilize cURL first, but falls back to various other methods if cURL is not available on the server.
• wp_remote_retrieve_body() - processes the response from the request, and retrieves the meat of it.
• json_decode() - decodes a JSON string into a native PHP string, array or object.

Adding a New Employee

The URL structure to create a new employee entry is /wp-json/wp/v2/employee. For instance, to add a new employee to the directory, you would send a POST request to http://umwwebmaster.staging.wpengine.com/directory/wp-json/wp/v2/employee.

The process is essentially the same as the process outlined above for editing an employee, but you will not include the ID parameter in your request body. You should, at a minimum, include the title, status (always set to publish), employee_username, employee_first-name and employee_last-name.

Updating Individual Meta Values

If you only need to update a single meta value, you can run a meta query against the API instead of editing the entire employee object.

If that is how you would prefer to update meta values, you would first send a request to /wp-json/wp/v2/posts/<post id>/meta to retrieve a list of all of the meta data already associated with the employee. If you find the key for the value that you're trying to update within that list, you will need to get the meta ID for that item. If you do not find that key in the list, you can move forward with adding new meta data.

Important The names of the meta data fields are different when going this route than they are when sending a request to update/add an employee. At the bottom of this document, you will find a key showing how the post fields (mentioned at the top of this document) map to the actual meta field names (which would need to be used when running a meta query).

Whether you are adding new meta data, or updating existing meta data, your request will need to include the following fields:

1. key - the name of the field being updated
2. value - the value being applied to that field

Editing Existing Meta Data

Once you have the meta ID for the field you are trying to update, you will send a PUT request to /wp-json/wp/v2/posts/<post id>/meta/<meta id>, and the body should contain the fields mentioned above.

Adding New Meta Data

If the meta field you're trying to manipulate does not already exist, you will need to send a POST request to /wp-json/wp/v2/posts/<post id>/meta, with the fields mentioned above in the body of the request.

Sample Code

Following is some sample WordPress PHP code showing how we might check to see if specific meta data already exists for a specific employee on the staging server, and then decide how to proceed based on that result.

<?php
/**
 * Set the authentication header
 */
$headers = array(
    'Authorization' => 'Basic ' . base64_encode( [username] . ':' . [password] ), 
);

/**
 * Set up an array to hold the information we want to add/modify
 */
$new_meta = array(
	'key' => 'wpcf-last-name', 
	'value' => urlencode( 'New Last Name' ), 
);

$post_id = 2162;
/**
 * Set the base URL
 */
$url = 'http://umwwebmaster.staging.wpengine.com/directory/wp-json/wp/v2/posts/' . $post_id . '/meta';

$args = array(
	'method'  => 'GET', 
	'headers' => $headers, 
	'body'    => '', 
);

/**
 * First, retrieve all of the meta data associated with the employee
 */
$request = wp_safe_remote_get( $url, $args );
$result = @json_decode( wp_remote_retrieve_body( $request ) );

/**
 * Loop through the meta data to see if our meta field exists or not
 */
foreach ( $result as $m ) {
	if ( $m->key != $new_meta['key'] )
		continue;

	$url .= '/' . $m->id;
	$new_meta['id'] = $m->id;
	$args['method'] = 'PUT';
}

if ( ! array_key_exists( 'id', $new_meta ) ) {
	$args['method'] = 'POST';
}

$url = add_query_arg( $new_meta, $url );
$request = wp_remote_request( $url, $args );
$result = @json_decode( wp_remote_retrieve_body( $request ) );

Post Fields Mapped to Meta Fields

As mentioned above, if you plan to run a query to update or add a post (employee, building, department, office, etc.), you should use the field names on the left below. If you are planning to run a meta query, you should use the field names on the right.

• employee_first-name <=> wpcf-first-name
• employee_last-name <=> wpcf-last-name
• employee_title <=> wpcf-title
• employee_email <=> wpcf-email
• employee_phone <=> wpcf-phone
• employee_office-room-number <=> wpcf-office-room-number
• employee_username <=> wpcf-username
• employee_building <=> _wpcf_belongs_building_id