- URL:
- https://<root>/<serviceName>/FeatureServer/synchronizeReplica
- Methods:
POST
- Required Capability:
- Create,Update,Delete,Sync
- Version Introduced:
- 10.0
Description
The synchronize
operation is performed on a feature service resource. This operation synchronizes changes between the feature service and a client based on the replica
provided by the client. Requires the sync capability. See Sync overview for more information on sync.
The client obtains the replica
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 edits
and edit
to identify a file containing the edits that were previously uploaded using the upload_item operation.
The response for this operation includes the replica
, new replica generation number, or the layer's generation numbers. The response has edits or layers according to the sync
/sync
. Presence of layers and edits in the response is indicated by the response
.
If the responseType is esri
or esri
, 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 sync
is per
and sync
is download or bidirectional, the synchronize
operation's response will have edits. If sync
is snapshot, the response will have replacement data.
If sync
is per
, and sync
have sync
as download or bidirectional, the response will have edits. If sync
have sync
as download or bidirectional for some layers and snapshot for some other layers, the response will have edits and data. If sync
for all the layers is snapshot, the response will have replacement data.
When sync
is per
, the create
and synchronize
operations' responses contain replica
. When sync
is per
, the create
and synchronize
operations' responses contain layer
.
You can provide arguments to the synchronize
operation as defined in the parameters table below.
New at 11.0
This operation includes a new parameter, reconcile
. This parameter applies to replicas created from branch versioned data where the service has the version
setting. Support for this parameter is indicated when the feature service has the supports
service-level property, under sync
, set as true
.
New at 10.9
- Starting at 10.9, it's possible to create replicas using the
server
target
andType bidirectional
sync
, enabling the ability to bidirectionally sync with another service. This is supported when theDirection supports
property isBi Directional Sync For Server 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 thereplica
on sync upload for theServer Sib Gen per
Replica sync
and theModel server
property in theSib Gen sync
parameter on sync uploadLayer per
Layer sync
. For more information on bidirectional sync, see Share content with collaboration groups.Model - A new parameter,
time
, has been added at 10.9. SettingReference Unknown Client time
asReference Unknown Client true
indicates 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
create
operation'sReplica sync
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, seeData Options sync
property values.Data Options
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 replica
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.
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 replica
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 unregister
operation or unregister replica geoprocessing tool. If a client asks for changes before the trim date/oldest replica
, the synchronize
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 synchronize
operation supports a replica
parameter which is used when syncing per
replicas with target
server
. When syncing per
replicas with target
server
, the sync
parameter can include a server
value for each layer.
Request parameters
Parameter | Details |
---|---|
(Required) | The ID of the replica you want to synchronize. Example
Example
|
|
For replicas with Syntax
Example
|
|
Replicas with the Syntax
Example
|
|
Values: |
| If Values: |
| If Values: |
| The edits the client wants to apply to the service. Alternatively, the 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
Syntax
Example
|
| If Values: |
| If Values: |
| Determines whether to upload, download, or upload and download on sync. By default, a replica is synchronized bi-directionally. Only applicable when
Values: |
|
If a sync operation has both the Syntax
Example
|
| The ID for the uploaded item that contains the edits the client wants to apply to the service. Used in conjunction with Example
|
| The data format of the uploaded data reference in Values: |
| The data format for the returned data. Values: |
| 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 When Values: |
| Introduced at ArcGIS Enterprise 11.0. This parameter applies to replicas created from branch versioned data where the service has the Values: |
| Setting 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 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 Value: |
|
The response format. The default response format is Values: |
Example usage
The following is a sample POST request for synchronize
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 data
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 data
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 transport
of esri
{
"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 transport
of esri
and a json
data
:
{
"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 transport
of esri
and sqlite
data
:
{
"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 per
sync
and a transport
of esri
:
{
"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 per
sync
and transport
of esri
:
{
"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
}
}
]
}