Rest - Admin - Change Log

Purpose

The intention of this API is to allow a system to keep in sync with the views server or trigger custom actions on data changes.

Please note: This API is still in development. While this API is stable and all the methods documented on this page will be improved rather than than changed, it will be with checking back with this documentation prior to any new interactions with this API.

Base URL

https://app.viewsapp.net/api/restful/admin/changelog

Basic Usage

curl --url <Base URL> -u<username>:<password> -H Content-Type:text/xml

This will return something similar to:

<?xml version="1.0" encoding="utf-8"?>
<changelog>
   <log id="8487">
       <object>Agency</object>
       <objectId>354</objectId>
       <action>edit</action>
       <timestamp>2014-02-07T10:42:40</timestamp>
       <username>nowhere.man</username>
   </log>
   <log id="8488">
       <object>PersonContact</object>
       <objectId>1</objectId>
       <action>update</action>
       <timestamp>2014-02-07T10:43:13</timestamp>
       <username>nowhere.man</username>
   </log>
   <log id="8489">
       <object>Booking</object>
       <objectId>245</objectId>
       <action>update</action>
       <timestamp>2014-02-07T10:43:26</timestamp>
       <username>nowhere.man</username>
   </log>
   <log id="8490">
       <object>SessionGroup</object>
       <objectId>8</objectId>
       <action>insert</action>
       <timestamp>2014-02-07T10:43:29</timestamp>
       <username>nowhere.man</username>
   </log>
   <log id="8492">
       <object>Participant</object>
       <objectId>25489</objectId>
       <action>update</action>
       <timestamp>2014-02-07T10:43:29</timestamp>
       <username>al.mccaig.transit</username>
       <relates>
           <Session>606</Session>
           <Person>1</Person>
       </relates>
   </log>
</changelog>

Object Specific Calls

If you are only interested to changes to a specific object, you can append the object name to the call:

curl --url <Base URL>/<objectType> -u<username>:<password> -H Content-Type:text/xml

• objectType - One for the following values
  • AgencyProject
  • Note
  • Participant
  • Person
  • PersonContact
  • Questionnaire
  • Session
  • SessionGroup
  • ValueList

e.g. for sessions

curl --url <Base URL>/session -u<username>:<password> -H Content-Type:text/xml

Restricting the changes by date

By default the API will return up to the last 4000 changes logged. However, you can fetch specific date ranges using the timestamp, you can also use the -from and -to modifiers to specify a date range:

curl --url <Base URL>/<objectType>?timestamp-from=<date>&timestamp-to=<date> -u<username>:<password> -H Content-Type:text/xml

An example use

This is an example script to check for changes of 3 objectTypes that occurred during the previous day and will build a list of object URL's for objects ready for fetching.

<?php
print "Begin...\n";


// The API credentials
$username = 'YOUR USERNAME';
$password = 'YOUR PASSWORD';

// Uncomment the the relevant API URL
//$baseURL = 'http://dev.views.coop/api/restful/';  // Development Server
$baseURL = 'http://testing.views.coop/api/restful/'; // Live Server
//$baseURL = 'https://app.views.coop/api/restful/'; // Live Server


if (!ini_get('display_errors')) {
    ini_set('display_errors', true);
}

function curl_download($Url, $params, $username, $password, $headers=''){
 
    // is cURL installed yet?
    if (!function_exists('curl_init')){
        die('Sorry cURL is not installed!');
    }
 
    // OK cool - then let's create a new cURL resource handle
    $ch = curl_init();
 
    // Now set some options (most are optional)
 
    $Url.='?'.http_build_query($params);
    
    // Set URL to download
    curl_setopt($ch, CURLOPT_URL, $Url);
    
    // Set username and password
    curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    
    // See if we pass any headers
    if (is_array($headers) && sizeof($headers)) {
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    }

    // User agent
    curl_setopt($ch, CURLOPT_USERAGENT, "APIChangeLogProcessor/1.0");
 
    // Include header in result? (0 = yes, 1 = no)
    curl_setopt($ch, CURLOPT_HEADER, 0);
 
    // Should cURL return or print out the data? (true = return, false = print)
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
    // Timeout in seconds
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
 
    // Download the given URL, and return output
    $output = curl_exec($ch);
 
    // Close the cURL resource, and free system resources
    curl_close($ch);
 
    return $output;
}


$baseURL .= '/admin/changelog';

// Use the following to define the desired file format
// Please Note: The json format has not been fully tested with these scripts
//$contentType = 'text/xml';
$contentType = 'application/json';
//$extension = 'xml';
$extension = 'json';

// I would not recomend fetching more than a days worth of changelogs. If you want to fecth more, then loop through the days individually
$params['timestamp-from'] = date('Y-m-d', strtotime('yesterday')); // Could be a param and set to an exact time it last ran

// You can use the updated field for person records
$objects = array('agencyproject', 'participant','session','sessionGroup');

$recordsToFetch = array();



// Loop through each of the change log objects
foreach( $objects as $thisObject ) {

    $response = json_decode(curl_download($baseURL.'/'.$thisObject, $params, $username, $password, array("Accept: {$contentType}")), true);;



    while( ($thisRecord = array_shift($response) ) ) {
        
        if (strtolower($thisRecord['object']) == 'participant') {
            if (!$thisRecord['relates']['Session']) {
                // There are a few cases where an extra log line is printed.
                // We just need to skip these
                continue;
            }
            
            $recordsToFetch[] = "/sessions/{$thisRecord['relates']['Session']}/participants";

        } else {
            $recordsToFetch[] = "/".strtolower($thisRecord['object'])."s/{$thisRecord['objectId']}";
        }
    }
    
    $thisRecord = $response = null; // Clean up to keep memory in control
    
}
sort($recordsToFetch);

$recordsToFetch = array_unique($recordsToFetch); // Strip duplicates

/**
 * $recordsToFetch should now contain a list of all the records you need to refresh
 * Which while testing on your data, a day and a half is returning < 4000 records to fetch
 */
print_r($recordsToFetch);
?>