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
- Creation date is in UTC with the following format "dd MMM yyyy HH:mm".
- 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 - 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.
- 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.
- "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.
- 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.
- parentid field within itemdetails element will hold 0 value for document delete and folder delete activities.
- File & folder permanent delete events are not recorded in the changes list of the changes API.
- 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) |
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
Imran Aziz I'm a bit confused about the use-case differences between the changes API endpoint and the DMS management API endpoints. Could you please explain when one might be better than the other?
Edit: preposition usage
Fernando Deleon yes obtaining the current sync_position is valid in version 2, and its global for the whole instance and not just for one site.
To get the current sync position is it still true on v2 to do a GET on /api/2/changes?sync_position=current.
Is the sync_position a value that is global to the whole site? or does it belong to a particular site?
Thanks
Comments
3 Comments