Synchronize Replica
- URL:https://<featureservice-url>/synchronizeReplica(POST only)
- Required Capability:Create,Update,Delete,Sync
- Version Introduced:10.0
Description
The synchronizeReplica operation is performed on a feature service resource. This operation synchronizes changes between the feature service and a client based on the replicaID provided by the client. Requires the sync capability. See Sync overview for more information on sync.
The client obtains the replicaID by first calling the createReplica operation.
Synchronize applies the client's data changes by importing them into the server's geodatabase. It then exports the changes from the server geodatabase that have taken place since the last time the client got the data from the server. Edits can be supplied in the edits parameter, or, alternatively, by using the editsUploadId and editUploadFormat to identify a file containing the edits that were previously uploaded using the upload_item operation.
The response for this operation includes the replicaID, new replica generation number, or the layer's generation numbers. The response has edits or layers according to the syncDirection/syncLayers. Presence of layers and edits in the response is indicated by the responseType.
If the responseType is esriReplicaResponseTypeEdits or esriReplicaResponseTypeEditsAndData, the result of this operation can include arrays of edit results for each layer/table edited as specified in edits. Each edit result identifies a single feature on a layer or table and indicates if the edits were successful or not. If an edit is not successful, the edit result also includes an error code and an error description.
If syncModel is perReplica and syncDirection is download or bidirectional, the synchronizeReplica operation's response will have edits. If syncDirection is snapshot, the response will have replacement data.
If syncModel is perLayer, and syncLayers have syncDirection as download or bidirectional, the response will have edits. If syncLayers have syncDirection as download or bidirectional for some layers and snapshot for some other layers, the response will have edits and data. If syncDirection for all the layers is snapshot, the response will have replacement data.
When syncModel is perReplica, the createReplica and synchronizeReplica operations' responses contain replicaServerGen. When syncModel is perLayer, the createReplica and synchronizeReplica operations' responses contain layerServerGens.
You can provide arguments to the synchronizeReplica operation as defined in the parameters table below.
New in 10.5.1
The synchronizeReplica operation supports a replicaServerSibGen parameter which is used when syncing perReplica replicas with targetType server. When syncing perLayer replicas with targetType server, the syncLayers parameter can include a serverSibGen value for each layer.
Request parameters
|
Parameter |
Details |
|---|---|
| f |
Description: The response format. The default response format is html. Values: html | json |
| replicaID | Required Description: The ID of the replica you want to synchronize. Syntax: replicaID=<replicaID> Example: replicaID={90F07F7B-991C-4818-B7CA-97B2BF4F7CAA} |
| replicaServerGen | Description: replicaServerGen is a generation number that allows the server to keep track of what changes have already been synchronized. A new replicaServerGen is sent with the response to the synchronizeReplica operation. Clients should persist this value and use it with the next synchronizeReplica call. It applies to replicas with syncModel = perReplica. For replicas with syncModel = perLayer, layer generation numbers are specified using parameter: syncLayers; and replicaServerSibGen is not needed. Syntax: replicaServerGen=<replicaServerGen> Example: replicaServerGen=2 |
| replicaServerSibGen | Description: replicaServerSibGen is a generation number that allows the server to keep track of what changes have already been received. It is set when synchronizing where syncModel = perReplica and targetType = server. The replicaServerSibGen is updated in the replica metadata on the replica resource once the process completes successfully. Replicas with targetType = server are designed to allow syncing between services. When syncing, the replicaServerSibGen value is derived from the replicaServerGen of the other services matching replica. For replicas with syncModel = perLayer, layer generation numbers are specified using parameter: syncLayers; and replicaServerGen is not needed. This value is not set for replicas where the targetType=client. Syntax: replicaServerSibGen=<replicaServerSibGen> Example: replicaServerSibGen=2 |
| transportType | Description: transportType represents the response format. If the transportType is esriTransportTypeUrl, the operation's response is contained in a file, and the URL link to the file is returned. Otherwise, the JSON object is returned directly in the response. The default is esriTransportTypeUrl. Note that for asynchronous processing (async=true), or when the response is returned in sqlite (dataFormat=sqlite ), results are always returned via URL regardless of how the parameter is set. Values: esriTransportTypeUrl | esriTransportTypeEmbedded |
| closeReplica | Description: If true, the replica will be unregistered when the synchronize completes. This is the same as calling synchronize and then calling unregisterReplica. Otherwise, the replica can continue to be synchronized. The default is false. Values: true | false |
| returnIdsForAdds | Description: If true, the objectIDs and globalIDs of features added during the synchronize will be returned to the client in the addResults sections of the response. Otherwise, the IDs are not returned. The default is false. Values: true | false |
| edits | Description: The edits the client wants to apply to the service. Alternatively, the editsUploadID and editsUploadFormat can be used to specify the edits in a delta file. The edits are described using an array where an element in the array includes:
For features, adds and updates are specified as feature objects that include geometry and attributes. Deletes can be specified using globalIDs for features and attachments. For attachments, updates and adds are specified using the following set of properties for each attachment. If embedding the attachment, set the data property; otherwise, set the url property. All other properties are required:
Syntax: Example: |
| returnAttachmentDatabyURL | Description: If true, a reference to a URL will be provided for each attachment returned from synchronizeReplica. Otherwise, attachments are embedded in the response. The default is true. Applies only if attachments are included in the replica. Values: true | false |
| async | Description: If true, the request is processed as an asynchronous job and a URL is returned that a client can visit to check the status of the job. See the topic on asynchronous usage for more information. The default is false. Values: true | false |
| syncDirection | Description: Determines whether to upload, download, or upload and download on sync. By default, a replica is synchronized bi-directionally. Only applicable when syncModel = perReplica. If syncModel = perLayer, sync direction is specified using syncLayers . Values: download | upload | bidirectional | snapshot
Example: syncDirection = download |
| syncLayers | Description: syncLayers allows a client to specify layer-level generation numbers for a sync operation. It can also be used to specify sync directions at layer-level. This parameter is needed for replicas with syncModel = perLayer. It is ignored for replicas with syncModel = perReplica. serverGen is required for layers with syncDirection = bidirectional or download. serverSibGen is needed only for replicas where the targetType = server. For replicas with syncModel = perLayer, the serverSibGen serves the same purpose at the layer level as the replicaServerSibGen does in the case of syncModel = perReplica. See the replicaServerSibGen parameter for more information. If a sync operation has both the syncDirection and syncLayersparameters, and the replica's syncModel is perLayer, the layers that do not have syncDirection values will use the value of the syncDirection parameter. If the syncDirection parameter is not specified, the default value of bidirectional is used. Values: download | upload | bidirectional | snapshot Syntax: Example: |
| editsUploadID | Description: The ID for the uploaded item that contains the edits the client wants to apply to the service. Used in conjunction with editsUploadFormat. Example: editsUploadID={300B4F9C-FAD6-4af3-88FD-DE77621FAFDD} |
| editsUploadFormat | Description: The data format of the uploaded data reference in editsUploadId .  Note:editsUploadFormat must reflect the data format of the uploaded item. Values: sqlite |
| dataFormat | Description: The data format for the returned data. Note:When the format is sqlite, a delta mobile geodatabase is returned which can be used in ArcGIS runtime applications. Values: json | sqlite |
| rollbackOnFailure | Description: Determines the behavior when there are errors while importing edits on the server during synchronization. This only applies in cases where edits are being uploaded to the server (syncDirection = upload or bidirectional). See the RollbackOnFailure and Sync Models topic for more details. When true, if an error occurs while importing edits on the server, all edits are rolled back (not applied), and the operation returns an error in the response. Use this setting when the edits are such that you will either want all or none applied. When false, if an error occurs while importing an edit on the server, the import process skips the edit and continues. All edits that were skipped are returned in the edits results with information describing why the edits were skipped. If the supportsRollbackOnFailure property is true, you can set the rollbackOnFailure parameter to true or false. If the supportsRollbackOnFailure property is false, the synchronizeReplica operation does not support the parameter. When supportsRollbackOnFailure is false and only a perLayer sync model is supported ("supportsPerLayerSync": true and supportsPerReplicaSync": false), synchronizeReplica always applies the rollbackOnFailure = false behavior above. When supportsRollbackOnFailure is false and only a perReplica sync model is supported ("supportsPerLayerSync": false and supportsPerReplicaSync": true), synchronizeReplica always applies the rollbackOnFailure = true behavior above. Values: true | false |
JSON request syntax
{
"replicaID": "<replicaID>", //unique value that identifies the replica/server
"replicaServerGen": "<serverGen>", //not needed if modelType is perLayer
"transportType": "<esriTransportTypeUrl | esriTransportTypeEmbedded>",
"closeReplica": "<false | true>",
"returnIdsForAdds": "<false | true>",
"edits": [
{
"id": <layerId1>,
"features": {
"adds": [<feature1>, <feature2>],
"updates": [<feature1>, <feature2>],
"deleteIds": [<globalId1>, <globalId2>]
},
"attachments": {
"adds": [<attachment1>, <attachment2>],
"updates": [<attachment1>, <attachment2>],
"deleteIds": [<globalId1>, <globalId2>]
}
},
{
"id": <layerId2>,
"features": {
"adds": [<feature1>, <feature2>],
"updates": [<feature1>, <feature2>],
"deleteIds": [<globalId1>, <globalId2>]
},
"attachments": {
"adds": [<attachment1>, <attachment2>],
"updates": [<attachment1>, <attachment2>],
"deleteIds": [<globalId1>, <globalId2>]
}
}
]
"returnAttachmentsDataByUrl": "<true | false>",
"async": "<false | true>",
"syncDirection": "<bidirectional | upload | download | snapshot>",
"syncLayers": [
{"id": <layerId1>, "serverGen": <genNum1>, "syncDirection": "syncDirection1"},
{"id": <layerId2>, "serverGen": <genNum2>, "syncDirection": "syncDirection2"}],
"editsUploadId": "<syncRequestUploadId>",
"editsUploadFormat"= "<sqlite>",
"rollbackOnFailure": "<false | true>",
"dataFormat"= "<json | sqlite>",
"f"= "<json | html>"
}
JSON request example (edits provided in uploaded file, and dataFormat=sqlite)
{
"replicaID": "{b7b70c50-7b8d-4938-a6f9-61f376e94c75}",
"replicaServerGen": 5, //empty if modelType is perLayer
"replicaServerSibGen": 10, //empty if modelType is perLayer
"transportType": "esriTransportTypeURL",
"closeReplica": false,
"returnIdsForAdds": false,
"edits": []
"returnAttachmentsDataByUrl": true,
"syncDirection": bidirectional,
"async": true,
"syncLayers":[]
"editsUploadId": "{300B4F9C-FAD6-4af3-88FD-DE77621FAFDD}",
"editsUploadFormat": "sqlite",
"dataFormat"= "sqlite"
"rollbackOnFailure": true,
"f"=json
}
JSON request example (edits in JSON, and dataFormat=json)
{
"replicaID": "{b7b70c50-7b8d-4938-a6f9-61f376e94c75}",
"replicaServerGen": , //empty if modelType is perLayer
"transportType": "esriTransportTypeEmbedded",
"closeReplica": false,
"returnIdsForAdds": false,
"edits": [
{
"id": 0,
"features": {
"adds": [
{
"geometry": {
"x": -120.739,
"y": 35.166
},
"attributes": {
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207000,
"GlobalID": "72e499ac-8bff-42e8-9897-12f121898565"
}
}
],
"updates": [
{
"geometry": {
"x": -120.54,
"y": 35.11
},
"attributes": {
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207300,
"GlobalID": "a699a609-8cbd-4a18-a363-42ac87e75e19"
}
}
],
"deleteIds": [
"{ed8e7ee8-4a91-4d5e-8bed-9f609c66387b}"
]
},
"attachments": {
"adds": [
{
"globalId": "AD5C23B6-27CD-4501-9A0D-C5C8DB774A38",
"parentGlobalId": "a699a609-8cbd-4a18-a363-42ac87e75e19",
"contentType": "image/jpeg",
"name": "manatee.jpg",
"uploadId": "c5210e85845a49018afb6028b05234f5"
}
],
"updates": [
{
"globalId": "6C78143A-231F-4CBB-BFFE-96F27B67E6FA",
"parentGlobalId": "85e499ac-8bff-42e8-9897-12f121898565",
"contentType": "image/jpeg",
"name": "salmon.jpg",
"uploadId": "92ea2e2bed874febab6bb8a0e1729c31"
}
],
"deleteIds": []
}
}
]
"returnAttachmentsDataByUrl": true,
"syncDirection": bidirectional,
"async": true,
"syncLayers":[{"id":0,"serverGen":8411,"syncDirection":"bidirectional"}]
"editsUploadId": "",
"editsUploadFormat": "",
"rollbackOnFailure": false,
"dataFormat"= "json",
"f"= "json"
}
Example usage
https://services.myserver.com/lidGgNLxw9LL0SbI/ArcGIS/rest/services/SaveTheBay/FeatureServer/synchronizeReplica
JSON response syntax (when transportType=esriTransportTypeEmbedded)
{
"transportType" : "<esriTransportTypeEmbedded | esriTransportTypeURL>",
"replicaID" : "<replicaID>", // unique value that identifies the replica/server
"replicaServerGen": , //only if modelType is perReplica
"layerServerGens": [ //only if modelType is perLayer
{"id":<layer1Id>,"serverGen":<genNum>},
{"id":<layer2Id,"serverGen":<genNum>}
],
"responseType": "<esriReplicaResponseTypeEdits | esriReplicaResponseTypeReplacementData |
esriReplicaResponseTypeEditsAndData | esriReplicaResponseTypeNoEdits>",
"edits": [
{
"id" : <layerId1>,
"features" : {
"adds":[<feature1>, <feature2>],
"updates":[<feature1>, <feature2>],
"deleteIds":["<globalId1>", "<globalId2>"],
"addResults":[], // reports errors, if any
"updateResults":[], // reports errors, if any
"deleteResults":[] // reports errors, if any
},
"attachments" : {
"adds":[<attachment1>, <attachment2>],
"updates":[<attachment1>, <attachment2>],
"deleteIds":["<globalId1>", "<globalId2>"],
"addResults":[], // reports errors, if any
"updateResults":[], // reports errors, if any
"deleteResults":[] // reports errors, if any
},
}, // end of layer 1 edits
{
"id" : <layerId2>,
"features" : {
"adds":[<feature1>, <feature2>],
"updates":[<feature1>, <feature2>],
"deleteIds":["<globalId1>", "<globalId2>"],
"addResults":[], // reports errors, if any
"updateResults":[], // reports errors, if any
"deleteResults":[] // reports errors, if any
},
"attachments" : {
"adds":[<attachment1>, <attachment2>],
"updates":[<attachment1>, <attachment2>],
"deleteIds":["<globalId1>", "<globalId2>"],
"addResults":[], // reports errors, if any
"updateResults":[], // reports errors, if any
"deleteResults":[] // reports errors, if any
},
} // end of layer 2 edits
] // end of edits
}
JSON response example (when transportType=esriTransportTypeURL and dataFormat=json)
{
"transportType":"esriTransportTypeUrl",
"responseType":"esriReplicaResponseTypeEdits",
"layerServerGens":[
{
"id":0,
"serverGen":1526606896310
}
],
"URL":"https://services.myserver.com/ArcGIS/rest/services/SaveTheBay/replicafiles/6169a9c5f6cc46e9b30afba6a125e4fc.json"
}
JSON response example (when transportType=esriTransportTypeURL and dataFormat=sqlite)
{
"transportType":"esriTransportTypeUrl",
"responseType":"esriReplicaResponseTypeEdits",
"layerServerGens":[
{
"id":0,
"serverGen":1526606896310
}
],
"URL":"https://services.myserver.com/ArcGIS/rest/services/SaveTheBay/replicafiles/_ags_data{756FD98A8F58464B96A2B1FB7BAE42BF}.geodatabase"
}
JSON response syntax (async=true and transportType=esriTransportTypeUrl)
When async=true, the request is processed as an asynchronous job and a URL is returned that a client can visit to check the status of the job.
{
"statusUrl": "<url>"
}
JSON syntax of status resource:
{
"transportType": "esriTransportTypeUrl",
"responseType": <esriReplicaResponseTypeEdits | esriReplicaResponseTypeEditsAndData| esriReplicaResponseTypeNoEdits>,
"replicaServerGen": "<replicaServerGen>",
"replicaName": "<replicaName>",
"replicaID": "<replicaID>",
"targetType": <"client" | "server">,
"resultUrl": "<url>", //path to JSON (dataFormat=JSON) or a SQLite geodatabase (dataFormat=sqlite)
"submissionTime": "<T1>", //Time since epoch in milliseconds
"lastUpdatedTime": "<T2>", //Time since epoch in milliseconds
"status": "<Pending | InProgress | Completed | Failed | ImportChanges | ExportChanges | ExportingData | ExportingSnapshot
| ExportAttachments | ImportAttachments | ProvisioningReplica | UnRegisteringReplica | CompletedWithErrors>"
}
JSON response example, perLayer sync model (when transportType=esriTransportTypeEmbedded)
{
"transportType" : "esriTransportTypeEmbedded",
"replicaID" : "{b7b70c50-7b8d-4938-a6f9-61f376e94c75}",
"layerServerGens" : [
{
"id" : 0,
"serverGen" : 8411
}
],
"responseType" : "esriReplicaResponseTypeEdits",
"edits" : [
{
"id" : 0,
"features" : {
"adds" : [
{
"geometry": {
"x": -120.41,
"y": 35.83
},
"attributes": {
"OBJECTID": 211,
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207302,
"GlobalID": "{b895c100-9ddc-5a32-b184-87db90a95e98}"
}
}
],
"updates" : [
{
"geometry": {
"x": -120.54,
"y": 35.11
},
"attributes": {
"OBJECTID": 139,
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207300,
"GlobalID": "{a699a609-8cbd-4a18-a363-42ac87e75e19}"
}
}
],
"deleteIds" : [
"{7BA1586C-A462-4F5A-BA3F-AC4B675829CD}",
"{6744DAA2-6E72-4025-B7C6-CDD8034CE127}"
],
"addResults" : [], //no errors for adds
"updateResults" : [], //no errors for updates
"deleteResults" : [] //no errors for deletes
},
"attachments" : {
"adds" : [],
"updates" : [],
"deleteIds" : [],
"addResults" : [], //no errors for adds
"updateResults" : [], //no errors for updates
"deleteResults" : [] //no errors for deletes
}
}
]
}
JSON response example, perReplica sync model (when transportType=esriTransportTypeEmbedded)
{
"transportType" : "esriTransportTypeEmbedded",
"replicaID" : "{b7b70c50-7b8d-4938-a6f9-61f376e94c75}",
"replicaServerGen" : 1368489013116,
"responseType" : "esriReplicaResponseTypeEdits",
"edits" : [
{
"id" : 0,
"features" : {
"adds" : [
{
"geometry": {
"x": -120.41,
"y": 35.83
},
"attributes": {
"OBJECTID": 211,
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207302,
"GlobalID": "{b895c100-9ddc-5a32-b184-87db90a95e98}"
}
}
],
"updates" : [
{
"geometry": {
"x": -120.54,
"y": 35.11
},
"attributes": {
"OBJECTID": 139,
"Type": 2,
"Confirmed": 0,
"Comments": "",
"Submitted": 1298911207300,
"GlobalID": "{a699a609-8cbd-4a18-a363-42ac87e75e19}"
}
}
],
"deleteIds" : [
"{7BA1586C-A462-4F5A-BA3F-AC4B675829CD}",
"{6744DAA2-6E72-4025-B7C6-CDD8034CE127}"
],
"addResults" : [], //no errors for adds
"updateResults" : [], //no errors for updates
"deleteResults" : [] //no errors for deletes
},
"attachments" : {
"adds" : [],
"updates" : [],
"deleteIds" : [],
"addResults" : [], //no errors for adds
"updateResults" : [], //no errors for updates
"deleteResults" : [] //no errors for deletes
}
}
]
}