SyncData Function

Format

b = syncdata(direction, dictionary_nameʃ, sync_universeʅ);

Description

The syncdata function transfers cases in a CSPro data source between a device and a synchronization service. Before calling syncdata, you must first connect to the service by calling syncconnect.

The function can upload cases from the local device (client) to the service as well as download cases from the service. The direction argument determines which of these operations is performed. It must be one of the following values:

GET: Download any cases that were modified on the service since the last sync and update or add them to the local data source.
PUT: Upload to the service any cases that were modified in the local data source since the last sync.
BOTH: Sync cases in the local data source with the service in both directions (i.e., perform both a GET and a PUT).

The dictionary_name argument must be the name of a data dictionary corresponding to the data source to synchronize. This dictionary must be an external dictionary, or the main dictionary of a data entry application. CSPro uses the data source that is currently associated with this dictionary, either because it was specified when the application started or via a call to setfile.

For synchronization with CSWeb, the dictionary must first be uploaded to CSWeb. See the CSWeb documentation for more information.

For Bluetooth peer-to-peer synchronization, the data is written to the data source associated with the dictionary of the same name on the device running the service. This means that both devices must have this dictionary added to the currently running CSPro application.

By providing an optional string expression for the sync_universe argument, you can limit the cases that are transferred. A synchronization universe is matched against the ID items of each of the cases. Cases are only transferred when the string of the ID items concatenated together starts with the universe. For example, if the universe is "123", then cases with IDs "1234" and "1235" would be synced but a case with IDs "2345" would not.

The syncdata function keeps track of which cases are transferred each time the client and service synchronize. This information is used to only transfer cases that have been modified since the last synchronization. This significantly reduces the amount of data transferred and therefore reduces bandwidth and the cost of air time. It also reduces the chance that two interviewers overwrite each other's work by both synchronizing to the same data source on the service. As long as the two interviewers do not modify the same case at the same time, they may both synchronize to the same service without overwriting each other's data.

The syncdata function is only supported when using CSPro DB or Encrypted CSPro DB data sources. Data sources in the legacy text format may not be synchronized using syncdata but instead can be transferred using the syncfile function. That function always transfers the entire data source, however, increasing the amount of data transferred and allowing for one interviewer to overwrite the changes of another.

An alternative to synchronizing data periodically is to use the CSWeb data source for data collection. Cases added or modified are directly updated on the server, as if syncdata were called after every action on a case.

You can use the synctime function to get the time of the last syncdata call.

Return Value

The function returns a logical value of 1 (true) if the transfer was successful and 0 (false) otherwise.

Example 1

if syncconnect("https://example.org/csweb/api") then

// send the latest survey data to the server
syncdata(PUT, SURVEY_DICT);

// get the latest assignments data from the server
syncdata(GET, ASSIGNMENTS_DICT);

syncdisconnect();

endif;

Example 2

if syncconnect("Bluetooth") then

// sync data for only the province and district assigned to the interviewer
string assignment_universe = maketext("%v%v", ASSIGNED_PROVINCE, ASSIGNED_DISTRICT);
syncdata(BOTH, CENSUS_DICT, assignment_universe);

syncdisconnect();

endif;