s = CS.Data.sync(syncId := ...
dataId := ...,
ʃ, direction := ...ʅ
ʃ, universe := ...ʅ) | Argument | Description | Types / Required |
|---|
| syncId | The resource ID returned by Sync.connect. | number
recommended |
| dataId | The resource ID returned by Data.open, or a dictionary name. | number, string
recommended |
| direction | The synchronization direction.
The default value is "both". | string
not required |
| universe | A universe to limit the cases that are synchronized. | string, array
not required |
The synchronization service is identified using
syncId, a
resource ID returned by
Sync.connect. While optional, this should generally be specified explicitly. (If there is only one synchronization session active, the resource ID can be calculated implicitly.)
The data source is identified using
dataId. If specified as a string, it references the data source that is connected to a dictionary that is part of an application. If specified as a number, it is processed as a
resource ID returned by
Data.open. This typically references non-application data sources. While optional, this should generally be specified explicitly. (If there is only one data source open, the resource ID can be calculated implicitly.)
The direction argument determines whether cases are uploaded, downloaded, or both. Options include:
- "get": Download any cases that were modified on the service since the last synchronization 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 synchronization.
- "both": Synchronize cases with the service in both directions (i.e., perform both a "get" and a "put").
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 universe argument, you can limit the cases that are transferred. The universe can be a single string, or an array of strings. When supplying an array, one synchronization operation will occur for each string in the array. 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.
Data synchronization routines keep 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. A data source's synchronization state can be retrieved using
Data.getSyncStatus. The action returns information including a list of cases that have not been synchronized.
Synchronizing data is only supported when using
CSPro DB or
Encrypted CSPro DB data sources. Data sources in the legacy
text format cannot be synchronized using
Data.sync 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
Data.sync were called after every action on a case.
The action returns an object containing information about the number of cases sent and received:
| Object | Property | Value |
|---|
| "sent" | "count" | Total number of cases sent to the synchronization service. Some of these cases may already exist on the synchronization service, so this value is not necessarily equal to the number of cases updated on the synchronization service. |
| "received" | "count" | Total number of cases received from the synchronization service. Some of these cases may already exist in the data source. |
| "received" | "new" | Number of received cases that existed only on the synchronization service. These cases are added to the data source. |
| "received" | "updates" | Number of received cases that existed on both the synchronization service and the data source, where the synchronization service version was newer. The corresponding cases in the data source are updated. |
| "received" | "stale" | Number of received cases that existed on both the synchronization service and the data source, where the data source version was newer. The received cases are ignored. |
| "received" | "conflicts" | Number of received cases that existed on both the synchronization service and the data source and were modified independently. These cases are treated as conflicts. CSPro ignores the synchronization service version and keeps the data source version. |
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The synchronization connection ID is not valid.
- The data source ID is not valid.
- The data source does not support synchronization.
- There is a network error while sending or receiving data from the synchronization service.
- There is an error interacting with the data source.
let dataId;
let syncId;
try {
// open the survey data
dataId = CS.Data.open({
connection: "molting-dates.csdb"
});
// connect to CSWeb, supplying the username and password
syncId = CS.Sync.connect({
connection: {
url: "https://example.org/csweb/api",
username: "jackw",
password: "MyPa$$w0rd!"
}
});
// synchronize the data, putting cases
CS.Data.sync({
syncId,
dataId,
direction: "put"
});
}
catch (error) {
print("Error syncing data: " + error);
}
finally {
// close the synchronization connection
if( syncId != undefined ) {
CS.Sync.disconnect({
syncId
});
}
// close the data source
if( dataId != undefined ) {
CS.Data.close({
dataId
});
}
}