This is the latest version of this API endpoint valid from Collaborate 4.1.4 and above, for older versions please see the child pages of this page

Problem Statement

Users in Collaborate are continuously updating content and collaborating with each other. API client displaying Collaborate updates to the user needs a way to get an update of the changes for each user. In order to obtain a list of changes, an API is required which will help the API client understand what has changed in Collaborate. 

Goal 

In order to fulfil current awareness requirement of Collaborate changes by the API client we have developed an API called "Changes API". 

This API helps to fetch a list of changes to the files/folder resource since the last sync operation by the client. The changes API is based on event/audit logs which make up our admin audit reports. The changes list is a time-sequenced list maintained separately for each user and device. We call it "sync_position". When a client application wants to fetch the changes since the last fetch operation, they send over their sync_position in the GET request and we return all changes since the sync_position. The content returned to the client are paginated. Individual resource items are embedded in the response content.

To initialize the client call the changes API with an empty sync_position and all events related to the specific folder will be sent to the client. The client can send a sync_position=current to get the current sync position.

Workflow of the client being setup for the first time

• A client that has just been configured can call sync_position = current to get the current sync position 
• Call the /files API to get a list of all of the files in the specific folder
• Call the /changes API to get hold of any changes since the sync_position = current
• Decide how frequent to call the server API based on the total_changes for the specific client on the server. 

The above call sequence will help the client to initialize the sync folder. 

Any actions taken by the specific client are recorded in the events log with the id of the specific source. 

Purpose

The purpose of this API is to provide changes to the system. Anyone can call this API to get sync changes detail.

version 1
 

Parameters

version 2

Parameters

Event Object

Global attributes 

User attributes

API Assumptions For Version 1

1.  Creation date is in UTC with the following format "dd MMM yyyy HH:mm".
2.  Optional query params details provided below
      syncpositionid : –  If next sync position id is provided then changes following that sync position will be returned otherwise response with current sync position id is given (without activities).If syncpositionid=0 then first 500 top activities will be given in response.
      limit : – This parameter can be used to limit the number of changes returned otherwise 500 changes are returned.
      contenttype : – To filter the result set by a specific content type like 'Files' (it is only one right now). If this parameter is set then will return a specific type of changes otherwise all type of content will be returned. "contenttype=files" will return both file and folder contents.
      siteid : – to get Changes by sourceclient basis. if provided then will give site specific sync changes otherwise not.
   Ex: /api/1/changes?syncpositionid=40&limit=30&contenttype=files&siteid=1
3.  If the user wants to provide the sourceclient for every API call(/User Events) then they need to provided dynamic value through the query parameter called "sourceclient" E.g. sourceclient=MyPC in the URL.
4.  The changes API response includes the "sourceclient" parameter information if populated. This is to allow the specific client application to ignore transactions registered by themselves. 
5.  "sourceclient" text limit is max 50 characters.If "sourceclient" test is longer than 50 characters then it will be automatically trimmed to first 50 characters.
6.  Changes API can be called by any Collaborate user with a minimum of "Content admin" rights. User with permissions less than "Content admin" will not see any changes when they call the Changes API, however, they can get the nextsyncpositionid.
7. parentid field within itemdetails element will hold 0 value for document delete and folder delete activities.
8. File & folder permanent delete events are not recorded in the changes list of the changes API.
9. A new eventid 16 has been added when a file is added to Collaborate from Microsoft Office Application. 

Response XML

If successful the response body will contain the following structure

<changes>
   <nextsyncposition>155</nextsyncposition>
   <items>
      <item>
         <changeid>105</changeid>
         <contenttype>CONTENT_FOLDER</contenttype>
         <eventid>11</eventid>
         <sourceclient>folderrestorepc</sourceclient>
         <createdby>
            <firstname>Saviz</firstname>
            <lastname>Izadpanah</lastname>
            <email>saviz.izadpanah@highq.com</email>
            <userid>11</userid>
         </createdby>
         <createddate>25 Sep 2014 13:44</createddate>
         <itemdetails>
            <id>41</id>
            <name>f2</name>
            <parentid>2</parentid>
         </itemdetails>
      </item>
      <item>
          <changeid>155</changeid>
         <contenttype>CONTENT_DOCUMENT</contenttype>
         <eventid>1</eventid>
         <sourceclient />
         <createdby>
            <firstname>Saviz</firstname>
            <lastname>Izadpanah</lastname>
            <email>saviz.izadpanah@highq.com</email>
            <userid>11</userid>
         </createdby>
         <createddate>25 Sep 2014 13:44</createddate>
         <itemdetails>
            <id>33</id>
            <name>ACE</name>
            <parentid>5</parentid>
         </itemdetails>
      </item>
   </items>
</changes>

Version 2

Response XML

If successful the response body will contain the following structure

<changes>
    <nextsyncposition>155</nextsyncposition>
    <items>
        <item>
            <changeid>105</changeid>
            <contenttype>CONTENT_FOLDER</contenttype>
            <eventid>11</eventid>
            <sourceclient>source client string</sourceclient>
                        <createddate>25 Sep 2014 13:44</createddate>
            <itemdetails>
                <id>41</id>
                <siteid>41</siteid>
                <parentid>2</parentid>
            </itemdetails>
        </item>
        <item>
            <changeid>155</changeid>
            <contenttype>CONTENT_DOCUMENT</contenttype>
            <eventid>1</eventid>
            <sourceclient>source client string</sourceclient>
                        <createddate>25 Sep 2014 13:44</createddate>
            <itemdetails>
                <id>33</id>
                <siteid>41</siteid>
                <parentid>5</parentid>
            </itemdetails>
        </item>
    </items>
</changes>

Changes list v1

Changes list v2

Managing changes API response for multiple sites

Register folder for Changes API based on sourceclient

Remove folder registration for Changes API based on sourceclient

Remove all folder registrations for Changes API based on sourceclient