Changes list

OVERVIEW



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
 

Resource(API) EndPoint Query Params HTTP Method Request XML Response XML Response Code
/api/1/changes

  Parameters

      GET   Response XML Response code

 

Parameters

Parameter Name Value Description

syncpositionid

int The start location for the content sync. All items from the syncpositionid will be returned. 
limit int The no of items to return for this request
contenttype string the type of content for which the changes are required, the default is all but you can folder the changes by the following content types
Files
siteid int User can filter by site

 

version 2

 

Resource(API) EndPoint Query Params HTTP Method Request XML Response XML Response Code
/api/2/changes

  Parameters

      GET   Response XML Response code

 

Parameters

Parameter Name Value Description

syncpositionid

int The start location for the content sync. All items from the syncpositionid will be returned. 
limit int The no of items to return for this request
contenttype string the type of content for which the changes are required, the default is all but you can folder the changes by the following content types
Files
sourceclient String Changes will be given on sourceclient basis
siteid int User can filter by site

 

Event Object

Global attributes 

Parameter Type Description
nextsyncposition int The next sync position the client should use to obtain changes

User attributes

Parameter Type Description
changeid int sync position id of each activity.
contenttype string Type of content, file or folder
eventid int the unique id for each event
createdby object the user who created the event, this is a user object
creationdate date The time the event was created
sourceclient string The dynamic id which is provided by client when calling API's to store in db, this will be returned to the client at the time of returning changes API results.
itemdetails object the metadata of the item which was modified. e,g content's id, name, parentid fields.

 

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>

 

Code Meaning
200 Get Changes List successfully
400

Problem with parsing XML or JSON object (Bad Request)

401 Unauthorized
403 Validation failed/ Forbidden
405 Method not allowed (calling API with the wrong method)
500 Internal error occurred

 

Event id User Event API version supported ItemID will be
1 File added 1 and 2 File id
2 File deleted 1 and 2 File id
3 File moved 1 and 2 File id
4 File name changed 1 and 2 File id
5 Folder added 1 and 2 Folder id
6 Folder deleted 1 and 2 Folder id
7 Folder moved 1 and 2 Folder id
8 Folder name changed 1 and 2 Folder id
9 New File version added 1 and 2 File id
10 File restore 1 and 2 File id
11 Folder restore 1 and 2 Folder id
12 File copied to [side] 1 and 2 File id
13 File copied from [side] 1 and 2 File id
14  Folder copied to [site] 1 and 2 Folder id
15  Folder copied from [site] 1 and 2 Folder id
16 File saved from Microsoft Office 1 and 2 File id
17 Site status change 2 NA
18 Enable IP restriction for site 2 NA
19 Enable Site Password for site 2 NA
20 Site Level Passcode enabled 2 NA
21 Site Terms and Condition enabled 2 NA
22 Sie Approval Document Work Flow enabled 2 NA
23 Site enabled with checkIn checkout 2 NA
24 Site DRM enable 2 NA
25 User suspended from site 2 user id
26 User removed from site 2 user id
27 Document module disabled from site 2 NA
28 Folder Permission Change 2 Folder id
29 File Permission Change 2 File id
30 User Role Updated in site 2 user id
31 Site Enforce User Group Property updated 2 NA
32 Site Permission Level Changed for file module 2 NA
33 Visible On Highq Drive property removed from site 2 NA
34 Folder Inheritance Changed 2 Folder id
35 My File Enabled 2 NA
36 My File Disabled 2 NA
37 User Role Updated From System Admin 2 user id
 
38 User removed from site group (4.0.5 onwards) 2 user id
39 User added to site group (4.0.6 onwards) 2 user id
40 Enable automatic Pdf Conversion 2 NA (Added in 4.1.4)
41 Disable automatic Pdf Conversion 2 NA (Added in 4.1.4)
42 Sent to DocuSign for eSigning 2 NA (Added in 4.1.4)
43 Sent to Adobe Sign for eSigning 2 NA (Added in 4.1.4)
44 Sign request revoked by sender 2 NA (Added in 4.1.4)
45 Signing lock removed by sender 2 NA (Added in 4.1.4)
46 Signed in DocuSign 2 NA (Added in 4.1.4)
47 Signed in Adobe Sign 2 NA (Added in 4.1.4)

 

 


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

Comments


3 Comments

Last Updated: Sep 22,2023