- 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 at 11.0
This operation includes a new parameter, reconcileBranchVersion. This parameter applies to replicas created from branch versioned data where the service has the versionPerDownloadedMap setting. Support for this parameter is indicated when the feature service has the supportsBranchVersionReconcile service-level property, under syncCapabilities, set as true.
New at 10.9
- Starting at 10.9, it's possible to create replicas using the server targetType and bidirectional syncDirection, enabling the ability to bidirectionally sync with another service. This is supported when the supportsBiDirectionalSyncForServer property is true. Currently, bidirectional syncing is limited to syncing a hosted feature service, or a feature service running on branch versioned or non-versioned with archiving data, with a hosted feature service. These created replicas require setting the replicaServerSibGen on sync upload for the perReplica syncModel and the serverSibGen property in the syncLayer parameter on sync upload perLayer syncModel. For more information on bidirectional sync, see Share content with collaboration groups.
- A new parameter, timeReferenceUnknownClient, has been added at 10.9. Setting timeReferenceUnknownClient as trueindicates that the client is capable of working with date field data values that are not in UTC. For more information on this parameter, see the Request parameters table below.
- The createReplica operation's syncDataOptions parameter has been expanded to add full annotation and an option to include a subset of Utility Network system information when taking data offline. For more information, see syncDataOptions property values.
New at 10.8.1
Feature services published with the Create a version for each downloaded map option will create a version for each replica that is created with branch versioned data. Edits uploaded during replica synchronization are applied to this version, whereas edits downloaded during replica synchronization are from the default version. Differences on default between the passed in replicaServerGen moment, and the common ancestor of default and the replica version determine the edits to download. In order to download edits, the replica version must be reconciled, or reconciled and posted, since the last sync. For more information, see Work with offline maps and branch versioned data.
Note:
Feature services can also be published with the none option, which will create and sync from the default branch version (as supported in previous releases).
ArcGIS Pro 2.6 introduced a new Trim Archive History geoprocessing tool that allows you to trim non-versioned archived data. If there are replicas, however, the trim date can't be before the oldest replica's replicaServerGen value when converted to an epoch date. You can remove old replicas that are no longer used and blocking the trim operation. For this, you can use the unregisterReplica operation or unregister replica geoprocessing tool. If a client asks for changes before the trim date/oldest replicaServerGen, the synchronizeReplica operation will error. Edits may still be uploaded, but a new replica will need to be created to get the latest from the service.
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 |
---|---|
replicaID (Required) | The ID of the replica you want to synchronize. Example
Example
|
replicaServerGen | 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
Example
|
replicaServerSibGen | 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 is perReplica and targetType is server. The replicaServerSibGen is updated in the replica metadata on the replica resource once the process completes successfully. This value is not set for replicas where the targetType is client. Replicas with the server targetType 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 perLayer as syncModel, layer generation numbers are specified using parameter: syncLayers; and replicaServerGen is not needed. Syntax
Example
|
transportType | 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 | 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 | 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 | 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 | 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. This only applies only if attachments are included in the replica. Values: true | false |
async | 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 | 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. The following values are accepted by this parameter:
Values: download | upload | bidirectional | snapshot |
syncLayers | 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 a syncModel of perLayer. It is ignored for replicas with a syncModel or perReplica. serverGen is required for layers with syncDirection = bidirectional or download. serverSibGen is needed only for replicas where the targetType is server. For replicas with a syncModel of perLayer, the serverSibGen serves the same purpose at the layer level as the replicaServerSibGen does in the case of a perReplica syncModel. See the replicaServerSibGenparameter 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. Syntax
Example
|
editsUploadID | The ID for the uploaded item that contains the edits the client wants to apply to the service. Used in conjunction with editsUploadFormat. Example
|
editsUploadFormat | The data format of the uploaded data reference in editsUploadId . Note:editsUploadFormat must reflect the data format of the uploaded item.Values: sqlite |
dataFormat | 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 | 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 (either upload or bidirectional for syncDirection). See the RollbackOnFailure and Sync Models topic for more details. If the supportsRollbackOnFailure property is false, the synchronizeReplica operation does not support the parameter. 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, the import process instead 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. When supportsRollbackOnFailure is false and only a perLayer sync model is supported (the supportsPerLayerSync property is true and the supportsPerReplicaSync property is false), synchronizeReplica always applies the rollbackOnFailure as false behavior above. When supportsRollbackOnFailure is false and only a perReplica syncModel is supported (the supportsPerLayerSync property is false and supportsPerReplicaSync is true), synchronizeReplica always applies the rollbackOnFailure as true behavior above. Values: true | false |
reconcileBranchVersion | Introduced at ArcGIS Enterprise 11.0. This parameter applies to replicas created from branch versioned data where the service has the versionPerDownloadedMap setting. Replicas created from these services will have an associated replica branch version. When set to true, the operation automatically reconciles the replica branch version with the default branch upon sync. The default value is false. Note:This parameter is supported by feature service's that have the supportsBranchVersionReconcile service-level property, under syncCapabilities, set as true. Values: true | false |
timeReferenceUnknownClient | Setting timeReferenceUnknownClient as trueindicates that the client is capable of working with data values that are not in UTC. If its not set to true, and the service layer's datesInUnknownTimeZone property is true, then an error is returned. The default is false Its possible to define a service's time zone of date fields as unknown. Setting the time zone as unknown means that date values will be returned as-is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the datesInUnknownTimeZone layer property as true. Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields which are stored and returned in UTC even when the time zone is set to unknown. Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service in order to avoid problems.. Setting this parameter to true indicates that the client is capable of working with unknown date values that are not in UTC. Note:ArcGIS Pro 2.7 or newer can work with these feature services. Value: true | false |
f | The response format. The default response format is html. Values: html | json |
Example usage
The following is a sample POST request for synchronizeReplica that explains the syntax this request, formatted for readability:
POST /webadaptor/rest/services/SaveTheBay/FeatureServer/synchronizeReplica HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
replicaID=<replicaID> //unique value that identifies the replica/server
&replicaServerGen=<serverGen integer> //not needed if modelType is perLayer
&transportType=<esriTransportTypeUrl | esriTransportTypeEmbedded>
&closeReplica=<true | false>
&returnIdsForAdds=<true | false>
&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=<true | false>
&syncDirection=<bidirectional | upload | download | snapshot>
&syncLayers=[
{
"id": <layerId1>,
"serverGen": <genNum1>,
"syncDirection": "syncDirection1"
},
{
"id": <layerId2>,
"serverGen": <genNum2>,
"syncDirection": "syncDirection2"
}
]
&editsUploadId=<syncRequestUploadId>
&editsUploadFormat=<sqlite>
&dataFormat=<json | sqlite>
&rollbackOnFailure=<true | false>
&reconcileBranchVersion=<true | false>
&f=<html | json | pjson>
Example one
The following example demonstrates a request with edits provided in an uploaded file and the dataFormat parameter set to sqlite.
POST /webadaptor/rest/services/SaveTheBay/FeatureServer/synchronizeReplica HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
replicaID={b7b70c50-7b8d-4938-a6f9-61f376e94c75}&replicaServerGen=5&replicaServerSibGen=10&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&reconcilveBranchVersion=false&f=pjson
Example two
This example demonstrates a request with edits provided as a JSON object and the dataFormat parameter set to json, formatted for readability:
POST /webadaptor/rest/services/SaveTheBay/FeatureServer/synchronizeReplica HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
replicaID={b7b70c50-7b8d-4938-a6f9-61f376e94c75}&replicaServerGen=[]&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=""&dataFormat=json&rollbackOnFailure=false&reconcilveBranchVersion=false&f=json
JSON Response syntax
Below is a sample JSON syntax that's returned when the request has a transportType of 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
}
Status URL and resource syntax
When async is set to 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>"
}
The following syntax is an example of the response returned by the 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 examples
Below is a sample JSON Response that's returned when the request has a transportType of esriTransportTypeURL and a json dataFormat:
{
"transportType":"esriTransportTypeUrl",
"responseType":"esriReplicaResponseTypeEdits",
"layerServerGens":[
{
"id":0,
"serverGen":1526606896310
}
],
"URL":"https://services.myserver.com/ArcGIS/rest/services/SaveTheBay/replicafiles/6169a9c5f6cc46e9b30afba6a125e4fc.json"
}
Below is a sample JSON Response that's returned when the request has a transportType of esriTransportTypeURL and sqlite dataFormat:
{
"transportType":"esriTransportTypeUrl",
"responseType":"esriReplicaResponseTypeEdits",
"layerServerGens":[
{
"id":0,
"serverGen":1526606896310
}
],
"URL":"https://services.myserver.com/ArcGIS/rest/services/SaveTheBay/replicafiles/_ags_data{756FD98A8F58464B96A2B1FB7BAE42BF}.geodatabase"
}
Below is a sample JSON Response that's returned when the request has a perLayer syncModel and a transportType of 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
}
}
]
}
Below is a sample JSON Response that's returned when the request has a perReplica syncModel and transportType of 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
}
}
]
}