Sync controller (/sync) | SenSeeAct Documentation

Returns statistics about new database actions in the tables of the specified project. The result can be used when you synchronize data from SenSeeAct to a local database. The endpoint

/sync/project/{project}/read

actually gets the database actions from the server, so they can be replicated in a local database. For this endpoint you can provide details about what you have synchronized earlier and you can limit the data to synchronize. You will get database actions for your own data or the data of a specified user.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to receive. Omit or leave empty to receive your own data.

JSON object with the following properties:

includeOwn

(optional) true if actions that were earlier synchronized from the remote database to the server, should be included. This can be done after a clean install of the remote database. The default is false.

progress

(optional) Array of progress objects (described below). You can omit tables where you have not synchronized anything.

includeTables

(optional) Array with names of the tables that should be synchronized. If this is not set or an empty list, it will synchronize all data tables, so this property limits that set. If any exclude tables are set, they will never be synchronized, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be synchronized. If this is not set or an empty list, it will synchronize all data tables or all include tables. Exclude tables are never synchronized, even if they appear in the include tables.

timeRangeRestrictions

(optional) Array with time range restrictions (described below). If you want to receive only records within a limited time range for a specific table, you can specify it here. The table must have a field “utcTime” or “localTime”. Otherwise the restriction is ignored.
Be aware of interference with the sync progress if in an earlier case you synchronized a later time range. For example one time you synchronize actions with this time range:
[2016-03-02 00:00:00, 2016-03-03 00:00:00]
The sync progress could then be 2016-03-02 18:30:00, but data before 2016-03-02 was not synchronized. If next time you synchronize actions with this time range:
[2016-03-01 00:00:00, 2016-03-02 00:00:00]
you won’t receive anything, because the sync progress has a later time.

You may omit any property or set it to null, or leave the entire content empty.

A progress object has the following properties:

table

Table name

user

This should be null and you may omit this property, but it will appear in the response.

time

The time of the last database action that was synchronized earlier, as a UNIX timestamp in milliseconds

order

The order number of the last database action that was synchronized earlier

A time range restriction is an object with the following properties:

table

Table name

startTime

UNIX time in milliseconds for the start (inclusive) of the range from which you want to receive records.
If the table has a field “utcTime”, then the time will be matched against that field.
Otherwise it will match against “localTime”. In that case the UNIX time is converted to a local time in time zone UTC.

endTime

UNIX time in milliseconds for the end (exclusive) of the range from which you want to receive records

JSON object with the following properties:

progress

The same progress as you specified in the request. This may be null.

count

The total number of (unmerged) new database actions. This is an estimation. The latestTime is retrieved after the count. If new database actions were added between them, the actual count will be higher.
The number of database actions you will receive from

/sync/project/{project}/read

can also be lower, because actions may be merged.

latestTime

The time of the latest database action, as a UNIX timestamp in milliseconds. This is null if there are no new database actions.

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/get-read-stats
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "includeOwn": false,
    "progress": [
        {
            "table": "steps",
            "time": 1442921321997,
            "order": 0
        },
        ...
    ],
    "includeTables": [ "steps" ],
    "excludeTables": [],
    "timeRangeRestrictions": [
        {
            "table": "steps",
            "startTime": 1442872800000,
            "endTime": 1442959200000
        }
    ]
}

Response

{
    "progress": [
        {
            "table": "steps",
            "user": null,
            "time": 1442921321997,
            "order": 0
        },
        ...
    ],
    "count": 1,
    "latestTime": 1442921356748
}

Returns new database actions in the tables of the specified project. You will get database actions for your own data or the data of a specified user. You can use this to synchronize data from SenSeeAct to a local database. To get only new records you should specify what you have synchronized earlier. You can also limit the data to synchronize.

To prevent memory problems due to a transfer of large amounts of data in one call, you can read new database actions in batches. Because new data may keep arriving between batches, the process may never end. Therefore you can also specify a maximum time. You can call

/sync/project/{project}/get-read-stats

to get the time of the latest database action (as well as the number of unmerged new actions). After that you can repeat this call to read the database actions in batches until the time that you got from

get-read-stats

.

The server tries to merge database actions before returning them. For example an insert and some updates on the same record can be merged into one insert. So the number of actions that you actually receive can be lower than the unmerged number that you got from

get-read-stats

.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to receive. Omit or leave empty to receive your own data.

JSON object with the following properties:

maxCount

(optional) The maximum number of database actions to return, or 0 (default) if there is no maximum. This is the batch size. For example 1000.

maxTime

(optional) The maximum time of a database action that is returned, or null (default) if there is no maximum. You can use the time returned by

/sync/project/{project}/get-read-stats

.

includeOwn

(optional) true if actions that were earlier synchronized from the client database to the server, should be included. This can be done after a clean install of the client database. The default is false.

progress

(optional) Array of progress objects (see below) that indicate what was synchronized earlier. This can be empty or null (default).

includeTables

(optional) Array with names of the tables that should be synchronized. If this is not set or an empty list, it will synchronize all data tables, so this property limits that set. If any exclude tables are set, they will never be synchronized, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be synchronized. If this is not set or an empty list, it will synchronize all data tables or all include tables. Exclude tables are never synchronized, even if they appear in the include tables.

timeRangeRestrictions

(optional) Array with time range restrictions (described below). If you want to receive only records within a limited time range for a specific table, you can specify it here. The table must have a field “utcTime” or “localTime”. Otherwise the restriction is ignored.
Be aware of interference with the sync progress if in an earlier case you synchronized a later time range. For example one time you synchronize actions with time range:
[2016-03-02 00:00:00, 2016-03-03 00:00:00]
The sync progress could then be 2016-03-02 18:30:00, but data before 2016-03-02 was not synchronized. If next time you synchronize actions with time range:
[2016-03-01 00:00:00, 2016-03-02 00:00:00]
you won’t receive anything, because the sync progress has a later time.

You may omit any property or set it to null, or leave the entire content empty.

A progress object has the following properties:

table

Table name

time

The time of the last database action that was synchronized earlier, as a UNIX timestamp in milliseconds

order

The order number of the last database action that was synchronized earlier

A time range restriction is an object with the following properties:

table

Table name

startTime

UNIX time in milliseconds for the start (inclusive) of the range from which you want to receive records.
If the table has a field “utcTime”, then the time will be matched against that field.
Otherwise it will match against “localTime”. In that case the UNIX time is converted to a local time in time zone UTC.

endTime

UNIX time in milliseconds for the end (exclusive) of the range from which you want to receive records

JSON array with database actions. A database action is an object with the following properties.

table

Table name

user

User ID of the user that you specified (or your own user ID)

action

INSERT, UPDATE, DELETE

recordId

The ID (UUID) of the affected record

jsonData

JSON string with an object with data for an insert or update action

sampleTime

Sample time of the affected record as a UNIX timestamp in milliseconds. This is only set if the table has field “utcTime” or “localTime”. If it only has a local time, then the sample time is the UNIX timestamp of the local time in time zone UTC.

time

Time of the database action as a UNIX timestamp in milliseconds

order

Order of the database action (to uniquely identify the synchronization progress if there are multiple actions with the same timestamp)

source

“local” or “remote”. If this is “local” (local to the server), it means that the action originates from the server. If it is “remote” (remote from the sever), it means that the action originates from yourself in an earlier database synchronization. If you set “includeOwn” to false, this should always be “local”.

author

This may be set for audit logging, but is null at the time of writing.

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/read
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "maxCount": 1000,
    "maxTime": 1442921356748,
    "includeOwn": false,
    "progress": [
        {
            "table": "steps",
            "time": 1442921321997,
            "order": 0
        },
        ...
    ],
    "includeTables": [ "steps" ],
    "excludeTables": [],
    "timeRangeRestrictions": [
        {
            "table": "steps",
            "startTime": 1442872800000,
            "endTime": 1442959200000
        }
    ]
}

Response

[
    {
        "table": "steps",
        "user": "b43f784d76c44e7a9ae0370b91521753",
        "action": "INSERT",
        "recordId": "4beadd197f784a4a8c2e1118915fb0c3",
        "jsonData": "{\"user\":\"b43f784d76c44e7a9ae0370b91521753\",
            \"utcTime\":1442737800000,
            \"timezone\":\"Europe/Berlin\",
            \"localTime\":\"2015-09-20T10:30:00.000\",
            \"value\":1172.0,
            \"id\":\"4beadd197f784a4a8c2e1118915fb0c3\"}",
        "sampleTime": 1442737800000,
        "time": 1442921356748,
        "order": 0,
        "source": "local",
        "author": null
    },
    ...
]

Registers a Firebase Cloud Messaging token to send push messages, for example to a mobile app, when new database actions occur in the tables of the specified project. You can filter database actions by including or excluding tables.

Registrations are identified by user, project and device ID. If you call this endpoint, any existing registration for the same project database, user and device ID will be overwritten.

When a database action occurs in a matching table, SenSeeAct will send an FCM data message like this:

{
    "to": "...",
    "priority": "high",
    "data": {
        "project": "default",
        "user": "b43f784d76c44e7a9ae0370b91521753",
        "table": "steps"
    }
}

The data field is a JSON object with the following properties:

project

Project code

user

User ID of the user to which the database action belongs

table

Table name where the database action occurred

The priority is set to ‘high’, which means that it will wake up a sleeping device, so the message should always be delivered as soon as possible when the device has a network connection.

When a client receives a push message, it should run

/sync/project/{project}/read

to get the database actions.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to receive. Omit or leave empty to receive your own data.

JSON object with the following properties:

fcmToken

Firebase Cloud Messaging client token. Push messages will be sent through FCM to this token.

deviceId

Device ID. This is used to identify push message registrations in SenSeeAct.

includeTables

(optional) Array with names of the tables that you want to watch to receive push notifications. If this is not set or an empty list, it will watch all data tables, so this property limits that set. If any exclude tables are set, they will never be watched, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be watched to receive push notifications. If this is not set or an empty list, it will watch all data tables or all include tables. Exclude tables are never watched, even if they appear in the include tables.

–

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/register-push
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "fcmToken": "...",
    "deviceId": "3aa96976b8938f04",
    "includeTables": [ "steps" ],
    "excludeTables": []
}

Response

–

Unregisters a Firebase Cloud Messaging token that was registered with

/sync/project/{project}/register-push

to send push messages when new database actions occur in the tables of the specified project. This endpoint removes a registration for the specified project database, user and device ID.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user for which you want to remove a push registration. Omit or leave empty for yourself.

deviceId

Device ID for which you want to remove a push registration.

–

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/unregister-push
    ?user=b43f784d76c44e7a9ae0370b91521753
    &deviceId=3aa96976b8938f04
X-Auth-Token: ...

Response

–

Consider using

/sync/project/{project}/register-push

instead of this endpoint. Like this endpoint it can be used to receive database actions immediately, but it will work better on mobile devices that may go to sleep.

Waits for new database actions in the tables of the specified project, and returns those actions. You will get database actions for your own data or the data of a specified user. Like

/sync/project/{project}/read

, you can use this to synchronize data from SenSeeAct to a local database, but you can use this call if you want to receive new actions as soon as possible, whereas

read

only polls for new messages. You should specify what you have synchronized earlier. You can also limit the data to synchronize.

If new database actions are available when you make the call, the actions will be returned immediately. Otherwise this call waits one minute and then returns with a timeout. To constantly receive new actions, you can keep repeating the call as soon as it returns.

To prevent memory problems due to a transfer of large amounts of data in one call, you can specify a batch size.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to receive. Omit or leave empty to receive your own data.

JSON object with the following properties:

maxCount

(optional) The maximum number of database actions to return, or 0 (default) if there is no maximum. This is the batch size. For example 1000.

progress

(optional) Array of progress objects (see below) that indicate what was synchronized earlier. This can be empty or null (default).

includeTables

(optional) Array with names of the tables that should be synchronized. If this is not set or an empty list, it will synchronize all data tables, so this property limits that set. If any exclude tables are set, they will never be synchronized, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be synchronized. If this is not set or an empty list, it will synchronize all data tables or all include tables. Exclude tables are never synchronized, even if they appear in the include tables.

timeRangeRestrictions

(optional) Array with time range restrictions (described below). If you want to receive only records within a limited time range for a specific table, you can specify it here. The table must have a field “utcTime” or “localTime”. Otherwise the restriction is ignored.
Be aware of interference with the sync progress if in an earlier case you synchronized a later time range. For example one time you synchronize actions with time range:
[2016-03-02 00:00:00, 2016-03-03 00:00:00]
The sync progress could then be 2016-03-02 18:30:00, but data before 2016-03-02 was not synchronized. If next time you synchronize actions with time range:
[2016-03-01 00:00:00, 2016-03-02 00:00:00]
you won't receive anything, because the sync progress has a later time.

You may omit any property or set it to null, or leave the entire content empty.

A progress object has the following properties:

table

Table name

time

The time of the last database action that was synchronized earlier, as a UNIX timestamp in milliseconds

order

The order number of the last database action that was synchronized earlier

A time range restriction is an object with the following properties:

table

Table name

startTime

UNIX time in milliseconds for the start (inclusive) of the range from which you want to receive records.
If the table has a field “utcTime”, then the time will be matched against that field.
Otherwise it will match against “localTime”. In that case the UNIX time is converted to a local time in time zone UTC.

endTime

UNIX time in milliseconds for the end (exclusive) of the range from which you want to receive records

JSON object with the following properties.

resultCode

OK: if new database actions were received. They are specified in the ‘actions’ property. After this you can repeat the call.
TIMEOUT: if one minute elapsed and no new database actions were received. After this you can repeat the call.
NO_DATA: if the project doesn’t have any database tables. This means that you should not repeat the call, because there will never be any data.

actions

If the result code is ‘OK’, then this is a JSON array with database actions (see below).

A database action is an object with the following properties.

table

Table name

user

User ID of the user that you specified (or your own user ID)

action

INSERT, UPDATE, DELETE

recordId

The ID (UUID) of the affected record

jsonData

JSON string with an object with data for an insert or update action

sampleTime

Sample time of the affected record as a UNIX timestamp in milliseconds. This is only set if the table has field “utcTime” or “localTime”. If it only has a local time, then the sample time is the UNIX timestamp of the local time in time zone UTC.

time

Time of the database action as a UNIX timestamp in milliseconds

order

Order of the database action (to uniquely identify the synchronization progress if there are multiple actions with the same timestamp)

source

This should be “local”. This property is used internally to prevent that database actions that you wrote to the server yourself, will be returned here.

author

This may be set for audit logging, but is null at the time of writing.

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/watch
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "maxCount": 1000,
    "progress": [
        {
            "table": "steps",
            "time": 1442921321997,
            "order": 0
        },
        ...
    ],
    "includeTables": [ "steps" ],
    "excludeTables": [],
    "timeRangeRestrictions": [
        {
            "table": "steps",
            "startTime": 1442872800000,
            "endTime": 1442959200000
        }
    ]
}

Response

{
    "resultCode": "OK",
    "actions": [
        {
            "table": "steps",
            "user": "b43f784d76c44e7a9ae0370b91521753",
            "action": "INSERT",
            "recordId": "4beadd197f784a4a8c2e1118915fb0c3",
            "jsonData": "{\"user\":\"b43f784d76c44e7a9ae0370b91521753\",
                \"utcTime\":1442737800000,
                \"timezone\":\"Europe/Berlin\",
                \"localTime\":\"2015-09-20T10:30:00.000\",
                \"value\":1172.0,
                \"id\":\"4beadd197f784a4a8c2e1118915fb0c3\"}",
            "sampleTime": 1442737800000,
            "time": 1442921356748,
            "order": 0,
            "source": "local",
            "author": null
        },
        ...
    ]
}

Returns details about what database actions have been synchronized earlier from a local database to the tables of the specified project in SenSeeAct. You can use this to determine what new database actions should be written in

/sync/project/{project}/write

. You can limit the tables to synchronize.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to write. Omit or leave empty if you want to write your own data.

JSON object with the following properties:

includeTables

(optional) Array with names of the tables that should be synchronized. If this is not set or an empty list, it will synchronize all data tables, so this property limits that set. If any exclude tables are set, they will never be synchronized, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be synchronized. If this is not set or an empty list, it will synchronize all data tables or all include tables. Exclude tables are never synchronized, even if they appear in the include tables.

You may omit any property or set it to null, or leave the entire content empty.

JSON array with progress objects. A progress object has the following properties:

table

Table name

user

User ID of the user that you specified (or your own user ID)

time

The time of the last database action that was synchronized earlier, as a UNIX timestamp in milliseconds

order

The order number of the last database action that was synchronized earlier

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/get-progress
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "includeTables": [ "steps" ],
    "excludeTables": []
}

Response

[
    {
        "table": "steps",
        "user": "b43f784d76c44e7a9ae0370b91521753",
        "time": 1442927787758,
        "order": 0
    },
    ...
]

Writes new database actions to the tables of the specified project. You can write database actions for your own data or the data of a specified user. The actions and embedded data will be validated. You can use this endpoint to synchronize data from a local database to SenSeeAct. You can call

/sync/project/{project}/get-progress

to determine what database actions were synchronized earlier. You can limit the tables to synchronize with “includeTables” and “excludeTables”. This means that actions for other tables result in an error.

Users need to have access to the specified project. Admins can access all projects.
All users can access their own data within a project that they can access.
Patients can only access their own data.
Professionals can access the data of users to whom they were granted access.
Admins can access all data.

{project}

Project code (see

/project/list

)

user

(optional) User ID of the user whose database actions you want to write. Omit or leave empty to write your own data.

JSON object with the following properties:

actions

Array of database actions (described below)

includeTables

(optional) Array with names of the tables that should be synchronized. If this is not set or an empty list, it will synchronize all data tables, so this property limits that set. If any exclude tables are set, they will never be synchronized, even if they appear in the include tables.

excludeTables

(optional) Array with names of the tables that should not be synchronized. If this is not set or an empty list, it will synchronize all data tables or all include tables. Exclude tables are never synchronized, even if they appear in the include tables.

A database action is a JSON object with the following properties:

table

Table name

user

User ID of the user that you specified (or your own user ID)

action

INSERT, UPDATE, DELETE

recordId

The ID (UUID) of the affected record

jsonData

JSON string with an object with data for an insert or update action

sampleTime

Sample time of the affected record as a UNIX timestamp in milliseconds. This is only set if the table has field “utcTime” or “localTime”. If it only has a local time, then the sample time is the UNIX timestamp of the local time in time zone UTC.

time

Time of the database action as a UNIX timestamp in milliseconds

order

Order of the database action (to uniquely identify the synchronisation progress if there are multiple actions with the same timestamp)

source

This should be “local”, but is ignored.

author

This may be set for audit logging, but should be null at the time of writing.

–

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/sync/project/default/write
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Content-Type: application/json
 
{
    "actions": [
        {
            "table": "steps",
            "user": "b43f784d76c44e7a9ae0370b91521753",
            "action": "INSERT",
            "recordId": "4beadd197f784a4a8c2e1118915fb0c3",
            "jsonData": "{\"user\":\"b43f784d76c44e7a9ae0370b91521753\",
                \"utcTime\":1442737800000,
                \"timezone\":\"Europe/Berlin\",
                \"localTime\":\"2015-09-20T10:30:00.000\",
                \"value\":1172.0,
                \"id\":\"4beadd197f784a4a8c2e1118915fb0c3\"}",
            "sampleTime": 1442737800000,
            "time": 1442921356748,
            "order": 0,
            "source": "local",
            "author": null
        },
        ...
    ],
    "includeTables": [ "steps" ],
    "excludeTables": []
}

Response

–

# Sync controller (/sync)

# /project/{project}/get-read-stats

# /project/{project}/read

# /project/{project}/register-push

# /project/{project}/unregister-push

# /project/{project}/watch

# /project/{project}/get-progress

# /project/{project}/write