s = CS.Data.getSyncStatus(dataId := ...,
ʃ, content := ...ʅ
ʃ, deviceId := ... ‖ deviceName := ... ‖ syncId := ...ʅ
ʃ, key := ... ‖ uuid := ... ‖ position := ...ʅ
ʃ, universe := ...ʅ
ʃ, limit := ...ʅ) | Argument | Description | Types / Required |
|---|
| dataId | The resource ID returned by Data.open, or a dictionary name. | number, string
recommended |
| content | The synchronization status content to query.
The default value is "summary". | string
not required |
| deviceId | A synchronization service's device ID, used to filter the content. | string
not required |
| deviceName | A synchronization service's device name, used to filter the content. | string
not required |
| syncId | A resource ID returned by Sync.connect, used to filter the content. | number
not required |
| key | The key (case IDs) of a specific case used to filter the content. | string
not required |
| uuid | The UUID of a specific case used to filter the content. | string
not required |
| position | The "position" of a specific case used to filter the content. | number
not required |
| universe | A universe to limit the cases that are considered as part of a synchronization status query. | string
not required |
| limit | The maximum number of results to return from the query. | number
not required |
The
Data.getSyncStatus action returns information about the
synchronization state of a
data source. The information returned is determined by
content. The action can return a list of cases that have not been synchronized, a list of devices that have been used for synchronization, and more.
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.)
Based on
content, the action can return information about all
synchronization services used for synchronization, or the content can be filtered for a particular service:
- Device ID: By specifying a deviceId, the content returned only pertains to synchronization with the service with the specified device ID. This ID can be retrieved using Sync.getConnectionInfo. An example of a CSWeb device ID is: "588850ce-330b-4afd-8282-7603e955a7a3".
- Device Name: By specifying a deviceName, the content returned only pertains to synchronization with the service with the specified device name. This name can be retrieved using Sync.getConnectionInfo. An example of a CSWeb device name is: "https://example.org/csweb/api/".
- Synchronization Service Connection: If connected to a synchronization service, you can use syncId to specify the resource ID returned by Sync.connect.
- If specifying multiple synchronization service identifiers, deviceId is prioritized over deviceName, and syncId is only used if a device is otherwise not identified.
The default option for content, "summary", returns an object with the synchronization history for the last get ("lastGet") and the last put ("lastPut"). If a device is specified, the last get and put values will be for that device; otherwise, the values are for synchronizations with any device. If a device is specified, or the data has only been synchronized with one service, then the number of cases that have not been put to the service is returned as the number "casesPendingSync".
The option for content, "syncHistory", returns an object containing the data source's synchronization history. This history, ordered from newest to oldest, is returned as an array ("syncHistory"). The last get and last put are also returned ("lastGet" and "lastPut"). If a device is specified, this history will be for that device. The amount of synchronization history processed can be reduced by specifying a limit.
The option for content, "syncServices", returns an array containing information about each of the synchronization services used for synchronizing the cases in the data source. Each object in the array contains the device ID, "deviceId", an array of names associated with the devices ("deviceNames"), and the times of the oldest and most recent synchronizations ("firstSyncTime" and "lastSyncTime").
The option for
content,
"casesPendingSync", returns an array of
case identifiers of cases that have not been put to a synchronization service, which generally means that the local version of the case has been modified. Each object in the array contains the identifiers
"key",
"uuid", and
"position". Because cases are synchronized on a per-device basis, you must specify a device (or the data must have only been synchronized with one service). The array of cases pending synchronization can be reduced by specifying a
limit. You can also specify a
"universe" to determine the cases that would be part of a synchronization operation that uses a universe.
The option for content, "caseStatus", returns an object with information about the synchronization status of a specific case. This object contains all the case identifiers ("key", "uuid", "position"), and an array, "syncHistory", containing the specific synchronization history of this version of the case. The only history returned pertains to the current version of the case, so if it is pending synchronization, then the array will be empty. If a device is specified, this history will be for synchronizations to that device.
- key: When specifying a key (case IDs), only non-deleted cases are matched.
- uuid: Specifying a case's UUID allows matching on all cases, including deleted cases. Note that not all data sources use UUIDs.
- position: Identification by the "location" of the case in the data source also matches on all cases. Note that the position value can change when the data source is modified.
One of these case identifiers must be specified. If multiple identifiers are specified, uuid is prioritized over position, which is prioritized over key.
The CSPro
logic function
synctime also returns information about a case's synchronization status.
The action returns an array or object containing the queried synchronization state. To see examples of the results, shown in JSON, see here:
Data.getSyncStatus Action Examples.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The data source ID is not valid.
- The data source does not support synchronization.
- The specified case does not exist in the data source.
- There is an error interacting with the data source.
- The synchronization connection ID is not valid.
- The query requires the specification of a device but no device is specified and it cannot be implicitly calculated.