The tracker is a machine answering to a specific set of operations. You can either access:
yourtracker.syncplanet.io/api,The basic operations are documented in the API Reference of damas-core.
Operations dedicated to the synchronization of the files contained in a folder tree.
publish - add some file(s) to the tracker's file indexGetting Started: Scripting guide to setup a scripting environment.
comment - write a text comment about the specified file(s)lock - lock some file(s) to inform the other users you will edit themunlock - unlock some file(s) that you previously lockedThe files are described as JSON objects where the _id key (identifier) is the path of the file using the UNIX path format (with / slash character as sub level delimiter).
{
"_id": "/file/path", /* String, UNIX path format */
"comment": "<text>", /* String, text comment of user when published */
"origin": "<volume>", /* String, volume name where the file is coming from */
"sync_priority": 0, /* Number, positive or negative, 0 is default (normal priority) */
"syncEverywhere": true /* Boolean, overide default behavior in globalParameters */
}
String file identifier using UNIX path format (slash characters as sub level delimiters). Always begins with a slash / character.
String the user text comment specified at publish.
scanned at <sitename> or modified at <sitename>String the name of the site on which the file was createdNumber order preference between files (higher values are first, can be negative, 0 is default)The system then insert keys on the published files. You can use them for monitoring and debug:
{
"author": "<@username>", /* String, user who did the publish */
"file_mtime": 1567529676000, /* Number, mtime on file systems (as epoch time in milliseconds) */
"file_size": 1286230019, /* Number, number of bytes */
"lock": "<@username>", /* String, username who is editing the file */
"modified_site5": 15676534821582, /* Number, when a modification was scanned on site5 */
"syncError_site2": 23, /* Number, error encountered on site2 (rsync exit status code) */
"syncLastAttempt_site2": 1567516933000, /* Number, time of last failed attempt on site2 */
"synced_site1": 15675564912347, /* Number, successful delivery time on site1 */
"synced_site3": 15675564591231, /* Number, successful delivery time on site3 */
"synced_site4": 15675565175645, /* Number, successful delivery time on site4 */
"time": 1567529676000 /* Number, time of the element, used at creation and element modification */
}
author the username who did the publish.
support is used if the file was discovered by Automatic File System Scansfile_mtime the value of the mtime attribute of the file in the file system (unix timestamp - epoch - in milliseconds)file_size the value of the size attribute of the file in the file system (size in bytes)modified_sitename unix timestamp in millisecondssyncError_sitename exit status code if an error occured on that site. 23 is: file not foundsyncLastAttempt_sitename: time of the last unsuccessful sync attempt for sitename. unix timestamp in millisecondssynced_sitename: time of the successful sync for sitename. unix timestamp in millisecondstime the overall time used to display and sort the elements in the interfaces. time is also used to compare the synced_* keys to know if a synchronized copy is outdated (yellow color is then used instead of green)The users are described as elements wearing some reserved keys: username, password, class plus optional keys.
{
"_id": "@username", /* String, unique user name identifying the user in the database */
"class": "editor", /* String, a user class for permissions. Could be guest, user, editor, admin */
"email": "usermail@address.com", /* String */
"fullname": "Firstname Lastname", /* String */
"password": "13d3a2a16c0cd2f7bf115d471999377e" /* String, hashed password */
}
The Authentication page gives more details about the authentication mechanism.
A set of generic CRUD functions is provided to create, read, modify and delete elements:
create - insert element(s) in the databaseread - retrieve element(s) using identifier(s)update - modify keys on existing element(s)upsert - create or modify element(s)delete - delete element(s)signIn- request an authentication token from the serversignOut - revoke a tokenverify - ask the server for the authentication status and usergraph - retrieve connected edges and nodes (recursive)search - find elements matching a query stringsearch_one - find first element matching a query stringsearch_mongo - find elements using a MongoDB query object (if MongoDB is the back-end)Lock file(s) for edition. Sets a lock key on elements with current authenticated username as value)
lock( identifiers [, callback] )
identifiers {string | array} : identifier(s) string to lockcallback {function} (js only, optional) : if specified, the request is asynchronous# Python
# lock one asset
project.lock('/project/path/to/file')
# True
# lock multiple assets in 1 request
project.lock(['/project/path/to/file1', '/project/another_file_path'])
# True
Add files to the index
publish( elements [, callback] )
Many options are provided at publish time, allowing Folder Packages and Destination Filtering.
elements {object | array} : object(s) to insert in the databasecallback {functon} (js only, optional) : if specified, the request is asynchronousnull (Javascript) or None (Python) on failureSame specifications as /api/create, except that it is expecting specific keys and a child element is created to keep track of the states upon publish
When we publish a file that is already tracked, the function returns an error
{
"_id": "/project/path/new_file",
"comment": "text",
"origin": "sitename"
}
Child node :
{
"_id": "55ae0b1ed81e88357d77d0e9",
"#parent" : "/project/path/new_file",
"comment": "text",
"origin": "sitename"
}
_id path or an array of pathsorigin alphanumerical name without space, for ease of use. For multi-site.optional keys (these keys are not mandatory but could ease multi sites configurations and version control):
file_mtime Number (milliseconds since 1 Jan 1970 00:00)file_size Number (number of bytes)version NumberIn a multi-site environment, the
originand_idpath are used to retrieve the file from the source server.
Unlock a locked asset
unlock ( identifiers [, callback] )
identifiers {string | array} : identifier(s) string(s) to lockcallback {function} (js only, optional) : if specified, the request is asynchronousIf the asset is not locked or locked for someone else (
lockkey value != authenticated user name) it returns false. If it was successfully unlocked, returns true.
Add a comment to one or several element(s)
comment ( elements [, callback] )
elements {object | array} : object(s) specifying the elements identifiers and comment stringcallback {function} (js only, optional) : if specified, the request is asynchronousnull (Javascript) or None (Python) on failureSets
authorkey on elements with the authenticated username as value, as well astimekey with the current time at creation.
# Python
# single parent id
>>> project.comment({"#parent" : "asset_id", "comment" : "text"})
{u'author' : u'username', u'time' : 1480588505449, u'#parent' : u'asset_id', u'comment' : u'text'}
# multiple parent ids
>>> project.comment({"#parent" : ["asset_id1", "asset_id2"], "comment" : "text"})
[{u'author' : u'username', u'time' : 1480588505449, u'#parent' : u'asset_id1', u'comment' : u'text'}, {u'author' : u'username', u'time' : 1480588505449, u'#parent' : u'asset_id2', u'comment' : u'text'}]
// Javascript
damas.comment({'#parent' : "asset_id", comment : "text"});
>> Object { author: "damas", time: 1480588505449, '#parent': "asset_id", comment: "text" }
// comment using an asynchronous call
damas.comment({'#parent' : "asset_id", comment : "text"}, function (node) {
// asynchronous mode
console.log(node.time);
});
The global configuration parameters are accessible through a JSON element that is used by the synchronization agents.
{
"_id": "rsyncGlobalParameters", /* generic parameter */
"enableScans": true, /* parameter for scans */
"excludePatternRules": "", /* parameter for scans */
"excludedFiles": "", /* parameter for scans */
"ignoreExistingFiles": false, /* parameter for scans */
"includePatternRules": "", /* parameter for scans */
"rsaPublicKey": "", /* key to install under volumes' .ssh/authorized_keys */
"sleepBetweenScans": 60, /* parameter for scans */
"syncEverywhere": true, /* [Destination Filtering](Destination-Filtering) */
"time": 1555711910004 /* generic parameter */
}
Each volume is described as an element which holds its configuration and options to control its behavior.
{
"_id": "sit/inthebox/mice/amopix", /* the volume identifier */
"agentStartTime": 1599731439000, /* agent time when launched */
"agentStatus": "on", /* status of the agent, on / off / undefined */
"agentVersion": "1.0.5", /* version of the running agent */
"author": "support", /* generic parameter */
"enableDiscovery": true, /* Boolean, filesystem scan switch */
"enableDiscoveryPackages": true, /* Boolean, filesystem scan switch */
"enableDiscoveryUpdatedFiles": true, /* Boolean, filesystem scan switch */
"enableDiscoveryDeletedFiles": true, /* Boolean, filesystem scan switch */
"enableEmission": true, /* Boolean, file emission switch */
"enableReception": true, /* Boolean, file reception switch */
"error": 0, /* Number, error encountered */
"exit_emission": 0, /* Number, error encountered */
"exit_reception": 0, /* Number, error encountered */
"exit_scan": 0, /* Number, error encountered */
"last_emission": 1571918493000, /* Number, last emission */
"last_reception": 1571910212000, /* Number, last reception */
"last_scan": 1571918421000, /* Number, last filesystem scan */
"lastConnectionAttempt": 1600942773000, /* Number, time of last connection attempt */
"lastConnectionStatusChange": 1600512139000, /* Number, time of previous status */
"lastConnectionSuccess": 1600942773000, /* Number, last successful connection to the volume */
"last_emission": 1600942573000, /* Number, last file emission time */
"last_reception": 1598770303000, /* Number, last file reception time */
"last_scan": 1600942965000, /* Number, last volume scan time */
"name": "amopix", /* String, volume's name */
"notifiedEmails": "" /* String, comma separated email addresses */
"rsync_args": "", /* String, arguments for rsync */
"rsync_env": "", /* String, environment for rsync */
"scan_duration": 14, /* Number, last filesystem scan duration */
"stderr_emission": "", /* String, stderr if emission error */
"stderr_scan": "", /* String, stderr if scan error */
"syncAmountEmission": 10, /* Number, Number of elements uploaded each time */
"syncAmountReception": 10, /* Number, Number of elements downloaded each time */
"time": 1563285980221, /* generic parameter */
"url": "ssh://user@adress:port/project/" /* String, URL of the volume */
}