SyncTime Function

Format

d = synctime(dictionary_nameʃ, device_identifier, case_identifierʅ);

Description

The synctime function returns the UNIX time of the last synchronization of a data file or a specific case, or notappl if no such synchronization has occurred. The dictionary_name argument indicates which data file's details are returned. This dictionary can be either the dictionary for the main data file or an external dictionary. CSPro uses the data file that is currently associated with this dictionary, either because it was specified when the application was started or via a call to setfile from application logic. Unlike the other synchronization functions, this function can be called without connecting to a server as it returns metadata stored offline in the CSPro DB file.

Providing an optional string expression device_identifier allows you to query the last synchronization time to a specific device. You can supply the identifier by using a name. A name like "Bluetooth" will return information on the last synchronization with any Bluetooth device. A name like "https://www.myserver.org/api" will return information on the last synchronization with the specified server.

Alternatively, you can specify device_identifier using a device ID. This is most relevant if trying to differentiate between Bluetooth syncs. The device ID corresponds to the value that would be returned by calling getdeviceid on the Bluetooth device of interest. For example, providing a device ID like "6ce7d9416fa72a85" will return information on the last synchronization with the device that has that ID. If no device_identifier is supplied, or if it is blank, then the function will return synchronization information for any device.

The optional string expression case_identifier allows you to specify a case UUID to get synchronization information on a case-by-case basis. A case's UUID is a value that uniquely identifies a case, even when multiple cases share the same key (ID items), and can be retrieved using the uuid function. The function only returns the synchronization time of the current iteration of the case, so if a case had been synced but has since been modified, the function will return notappl.

Return Value

The function returns the time of the last synchronization, or notappl if there was not a synchronization. In summary:

Device Identifier	Case Identifier	Last Synchronization Time...
Undefined or Blank	Undefined or Blank	...of any case to any device
Not Blank	Undefined or Blank	...of any case to the specified device
Blank	Not Blank	...of the specified case to any device
Not Blank	Not Blank	...of the specified case to the specified device

Example 1

numeric unsynced_cases = countcases(SURVEY_DICT where synctime(SURVEY_DICT, "", uuid(SURVEY_DICT)) = notappl);

if unsynced_cases > 0 then
errmsg("There are %d cases on your device that have not been synced to any device.", unsynced_cases);
endif;

Example 2

string ServerUrl = "https://www.myserver.org/api";
numeric SecondsInWeek = 60 * 60 * 24 * 7;

when synctime(SURVEY_DICT, ServerUrl);
notappl -> errmsg("You have never synced. Please sync as soon as possible.");
< ( timestamp() - SecondsInWeek ) -> errmsg("You have not synced in a week. Please sync as soon as possible.");
endwhen;