Create Replica

Description

The createReplica operation creates the replica between the feature service and a client based on a client-supplied replica definition. This operation requires that the feature service has the Sync capability enabled. For more information on the Sync capability, see Sync overview.

The response for createReplica includes the replicaID, server generation number, and data similar to the response from the feature service query operation. As the response returned by the createReplica operation has data for the layers in the replica, the response type for this operation is esriReplicaResponseTypeData. If the operation is called to register existing data using the replicaOptions parameter, the response won't contain data for the layers in the replica, and the response type will be esriReplicaResponseTypeInfo.

For detailed examples, see Sync workflow examples.

You can provide arguments to the createReplica operation as defined in the request parameters table below.

NoteNote:

Creating a replica from a service with only Query and Sync capabilities as an owner or an administrator creates a bidirectional replica (allows sync upload). Creating a replica from a service with Query and Sync capabilities as a nonowner creates a download replica that only allows sync downloads (edits can't be uploaded during sync). This allows owners or administrators to sync edits and manage the data while providing read-only access to other users.

At ArcGIS 10.6.1, there's an exception to this rule for feature services running on versioned data with only Query and Sync capabilities. In this case, a download replica is created for all users including owners and administrators. To administer the data, owners or administrators can use direct connections to the back end enterprise geodatabase in ArcGIS Pro. This exception means that all replicas created from these services will download from the published version on sync.

New at 11.0

New at 10.9.1

Feature service and feature service layer resources now include a supportedExportFormats property that describes the formats supported when exporting data. Data can be exported when either the extract or sync capabilities are enabled and the createReplica operation is called with the syncModel parameter set as none.

New at 10.9

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. In order to ensure that replica version names are unique, each name is derived using the name of the feature service, the name of the portal account that downloaded the map, and a unique ID. Note that the service name and user name sections of the replica version name may be truncated if the resulting name is longer than what the replica version name allows as it's maximum character length. For more information, see Offline Maps and Branch Versioned Data.

NoteNote:

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).

NoteNote:

Create replica requires user credentials for branch versioned services with the Create a version for each downloaded map option. An error is returned if run as an anonymous user.

New at 10.7

New at 10.5.1

Request parameters

Parameter

Details
replicaName

(Optional)

The name of the replica on the server. The replica name is unique per feature service. If not specified, a replica name will be assigned and returned in the createReplica response. If specified, but the replicaName already exists on the server, a unique name will be returned in the response using the given replicaName as a base (that is, MyReplica may be returned as MyReplica_0 if there is already a replica named MyReplica on the server).

Syntax

replicaName=<replicaName>

Example

replicaName=myReplica
layers

(Required)

The list of layers and tables to include in the replica.

Syntax

layers=[<layer1>, <layer2>, <table1>]

Examples

layers=0, 1, 2
layers=[0, 1, 2]
layerQueries

(Optional)

This parameter allows you to set properties on a per-layer or per-table basis. In addition to the layers and geometry parameters, the layerQueries parameter can be used to further define what is replicated. Only the properties for the layers and tables that you want changed from the default are required. If a layer's ID is present in the layers parameter and missing from layerQueries, its features that intersect with the filter geometry are returned.

The properties include the following:

  • where—Defines an attribute query for a layer or table. The default is no where clause.
  • useGeometry—Determines whether to apply the geometry for the layer. The default is true. If set to false, other layerQueries properties such as where determine which features are added.
  • includeRelated—Determines whether to add related rows. The default is true. Value true is honored only for queryOption = none. This is only applicable if your data has relationship classes. Relationships are only processed in a forward direction from origin to destination.
  • queryOption—Defines whether and how filters will be applied to a layer. queryOption was added at 10.2. See the Compatibility notes topic for more information.

    Values: <none | useFilter | all>

    When the value is none, no features are returned based on where and filter geometry. If includeRelated is false, no features are returned. If includeRelated is true, features in this layer (that are related to the features in other layers in the replica) are returned.

    When the value is useFilter, features that satisfy filtering based on geometry and where are retuned. The value of includeRelated is ignored.

    When the value is all, all the features from the layer are returned. All other parameters for the layer query are ignored.

Syntax

layerQueries={ Layer_or_tableID1 : {"where":"attribute query" , "useGeometry" : true | false, "includeRelated" : true | false}, Layer_or_tableID2: {.}}

Example

//Replicate facilities in an area that needs inspection (facilities layer id=0 and inspection layer id=1)
layerQueries = {"0":{"queryOption": "useFilter", "useGeometry": true, "where": "requires_inspection = Yes"}}


//Replicate facilities in an area that needs inspection and their related inspections
layerQueries = {"0":{" queryOption": "useFilter", "useGeometry": true, "where": "requires_inspection = Yes"}, {"1":{"queryOption": "none", "includeRelated": true}}

//Replicate all aircraft in a layer
layerQueries = {"2":{"queryOption": "all"}}

//Replicate all international aircraft
layerQueries = { "2":{"queryOption": "useFilter", "useGeometry": false, "where": "international= true" }}

//Upload a device's GPS tracks and not get any tracks back
layerQueries ={"3":{"queryOption": "none", "includeRelated": false}}
geometry

(Required)

The geometry to apply as the spatial filter. All the features in layers intersecting this geometry will be replicated. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, for envelopes and points, you can specify the geometry with a simpler comma-separated syntax.

Syntax

//JSON structures
geometryType=<geometryType>&geometry={ geometry}

//Envelope simple syntax
geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>

//Point simple syntax
geometryType=esriGeometryPoint&geometry=<x>,<y>

Example

//Envelope examples
geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}
geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41

//Point example
geometryType=esriGeometryPoint&geometry=-104,35.6
geometryType

(Optional)

The type of geometry specified by the geometry parameter. The geometry type can be an envelope, point, line, or polygon. The default geometry type is an esriGeometryEnvelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

inSR

(Optional)

The spatial reference of the input geometry. The spatial reference can be specified as either a well-known ID or a spatial reference JSON object, which can be defined using either a well-known ID (wkid) or a well-known text (wkt). If inSR is not specified, the geometry is assumed to be in the spatial reference of the map.

CautionCaution:

This parameter is required when createReplica is being performed on feature service views and has a wkt spacial reference. Not providing this parameter in this instance will cause the operation to fail.

replicaSR

(Optional)

The spatial reference of the replica geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object, which can be defined using either well-known ID (wkid) or well-known text (wkt). If the replicaSR is not specified, the replica data will be in the spatial reference of the map.

transportType

(Optional)

This parameter represents the response format. If esriTransportTypeUrl, the JSON response is contained in a file, and the URL link to the file is returned. Otherwise, the JSON object is returned directly. The default is esriTransportTypeUrl.

NoteNote:

If async is true, the results will always be returned as if transportType is esriTransportTypeUrl. If dataFormat is sqlite, the transportFormat will always be esriTransportTypeUrl regardless of how the parameter is set.

Values: esriTransportTypeUrl | esriTransportTypeEmbedded

returnAttachments

(Optional)

This parameter is only applicable if the feature service has attachments. If true, attachments are added to the replica and returned in the response. Otherwise, attachments are not included. The default is false.

Values: true | false

returnAttachmentsDatabyURL

(Optional)

This parameter is only applicable if the feature service has attachments and if returnAttachments is true and f=json. If true, a reference to a URL will be provided for each attachment returned from createReplica. Otherwise, attachments are embedded in the response. The default is true.

Values: true | false

attachmentsSyncDirection

(Optional)

Introduced at 10.4. This parameter is available when the service resource syncCapabilities property includes "supportsAttachmentsSyncDirection" : true Clients can specify the attachmentsSyncDirection when creating a replica. This parameter defines how attachments will be synced and is only applicable if the feature service has attachments.

NoteNote:

attachmentsSyncDirection is set during the createReplica operation and cannot be overridden during sync.

Values include the following:

  • bidirectional—Attachment edits can be both uploaded from the client and downloaded from the service when syncing.
  • Upload—Attachment edits can only be uploaded from the client when syncing. When the client calls synchronizeReplica, feature and row edits will be downloaded but attachments will not be. This is useful in cases where the data collector does not want to consume space with attachments from the service, but does need to collect new attachments.
  • None—Attachment edits are never synced from either the client or the server.

When returnAttachments is set to true, you can set attachmentsSyncDirection to either bidirectional (default) or upload. In this case, createReplica includes attachments from the service.

When returnAttachments is set to false, you can set attachmentsSyncDirection to either upload or none (default). In this case, createReplica does not include attachments from the service.

All other combinations are not valid.

Values: bidirectional | upload | none

async

(Optional)

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

syncModel

(Optional)

This parameter is used to indicate that the replica is being created for per-layer sync or per-replica sync. To determine which model types are supported by a service, query the supportsPerReplicaSync, supportsPerLayerSync, and supportsSyncModelNone properties of the feature service. By default, a replica is created for per-replica sync. If syncModel is perReplica, the syncDirection specified during sync applies to all layers in the replica. If the syncModel is perLayer, the syncDirection is defined on a layer-by-layer basis.

If syncModel is perReplica, the response will have replicaServerGen. A perReplica syncModel requires the replicaServerGen on sync. The replicaServerGen tells the server the point in time from which to send back changes. If syncModel is perLayer, the response will include an array of server generation numbers for the layers in layerServerGens. A perLayer sync model requires the layerServerGens on sync. The layerServerGens tell the server the point in time from which to send back changes for a specific layer.

syncModel can be set to none to export the data without creating a replica. Query the supportsSyncModelNone property of the feature service to see if this model type is supported. Starting at 10.9.1, the feature service and feature service layer resource's supportedExportFormats property describes the supported output dataFormats when using syncModel as none. See the RollbackOnFailure and Sync Models topic for more details.

Values: perReplica | perLayer | none

dataFormat

(Optional)

The format of the replica geodatabase returned in the response. The default is json.

NoteNote:
When the format is sqlite, a mobile geodatabase is returned, which can be used in ArcGIS Runtime applications.

Syntax: sqlite | filegdb | shapefile | json

replicaOptions

(Optional)

This parameter instructs the createReplica operation to create a new replica based on an existing replica definition (refReplicaId). The operation will create a replica but will not return data. The responseType returned in the createReplica response will be esriReplicaResponseTypeInfo.

To use replicaOptions to create a new replica based on an existing replica definition, it must include the registerExistingData property and reference an existing replica definition (refReplicaId).

The new replica will have the definition of the reference replica, which is identified by refReplicaId. The replica definition consists of parameters: layers, layerQueries, geometry, geometryType, inSR, returnAttachments, and syncModel.

The replicaOptions parameter can be used to either create a new replica based on an existing replica definition or to include layers that are not of "type": "feature layer" or "type": "table" in the replica. Both types of replica options cannot be used together in one call.

refReplicaServerGen is the generation number of the data from the reference replica. It applies to the reference replica created with syncModel = perReplica. refLayerServerGens is an array of layers' generation numbers in the reference replica. It applies to the reference replica created with syncModel = perLayer.

Either refReplicaServerGen or refLayerServerGens should be provided, not both. If the syncModel of the reference replica is perLayer, then refLayerServerGens should be provided. If the syncModel of the reference replica is perReplica, then refReplicaServerGen should be provided. If syncModel is set, it will be ignored.

If refReplicaId is specified and the replica is present on the server, its definition is used while creating a new replica. If the reference replica is specified and no longer present, the operation will return an error. If the reference replica is no longer available, the parameters that define the replica are required.

The server will return the provided refReplicaServerGen/ refLayerServerGens in the response. If refReplicaServerGen (or refLayerServerGens) is not specified in the parameter, the server will return new generation numbers. In this case, the client will not be able to get the changes, if any, from the time of reference replica creation to the time of new replica creation.

NoteNote:

Starting in 10.7, the registerExistingData option can be used with traditionally versioned data (layer property "isDataVersioned": true) as indicated with the "supportsRegisteringExistingData": true, property on the service. Using registerExistingData with traditionally versioned data requires the reference replica to have never been synced. If the reference replica needs to be updated, it must be dropped and re-created.

Syntax

replicaOptions = {"registerExistingData":{"refReplicaId": "<replica_guid>", "refReplicaServerGen": <genNum>, "refLayerServerGens": [{"id": <layer1Id>, "serverGen": <genNum>}, {"id": <layer2Id>, "serverGen": <genNum>}]}}

Example

replicaOptions = {"registerExistingData": {"refReplicaId": "{4721B2DD-CAE4-4a0f-B4E2-EAEB0AA80B0A}", "refReplicaServerGen": 100}}

eplicaOptions = {"registerExistingData": {"refReplicaId": "{313E3D39-8BAC-4e40-99DC-548A015E27FA}", "refLayerServerGens": [{"id": 0, "serverGen": 0}, {"id": 1, "serverGen": 0}]}}

For replicaOptions, syncDataOptions is used to include additional content other than layers ("type": "feature layer") or tables ("type": "table") in the replica. The syncDataOptions property can be used if the service-level supportedSyncDataOptions property is set. The example below includes all of the supported syncDataOptions, each representing a different bit and can be bitwise ORd. For more information on these values, see the syncDataOptions property values section below.

//(bit 0): Includes annotation features
{"syncDataOptions": 1}

//(bit 1): Includes dimension feature layers
{"syncDataOptions": 2}

//(bit 2): Includes contingent values
{"syncDataOptions": 4}

//(bit 3): Not in use
{"syncDataOptions": 8}

//(bit 4):  Introduced at 10.9. Includes a subset of Utility Network system information, including the utility network layer metadata, associations, rules, and subnetworks.
{"syncDataOptions": 16}

//(bit 5):   Added at 10.9. Includes full model annotation. When calling createReplica, you would set 33 to get the full model. This is a combination of syncDataOptions 1 (include annotation) and syncDataOptions 32, making it full model annotation
{"syncDataOptions": 32}

//(bit 6): Not in use
{"syncDataOptions": 64}

//(bit 7): Introduced at 11.0. Includes additional utilit network system tables
{"syncDataOptions": 128}

//(bit 8): Introduced at 11.0. This preserves true curves when taking data offline and syncing.
{"syncDataOptions": 256}

To set multiple syncDataOptions, the values can be summed (i.e, bitwise OR of these values). For example, to include annotation (syncDataOptions 1) and dimension layers (syncDataOptions 2), use:

{“syncDataOptions”: 3}

To include annotation layers (syncDataOptions 1), dimension layers (syncDataOptions 2), and contingent values (syncDataOptions 4), use:

{“syncDataOptions”: 7}

Note in these cases that the layer parameter is required to include the annotation or dimension layers you want to add to the replica.

The value of the supportedSyncDataOptions property indicates which values can be used with the feature service. It is also a bitwise ORd value. For example, a value of 3 for supportedSyncDataOptions indicates that there is at least one annotation layer and one dimension layer in the service. If syncDataOptions is 0, the input will be treated as if the parameter was not passed in the request.

For more information, see syncDataOptions property values section below.

Syntax

replicaOptions={"syncDataOptions": <syncDataOptions>}

Example

//Includes contingent values
replicaOptions = {"syncDataOptions": 4}
targetType

(Optional)

Introduced at 10.5.1. A targetType of client will generate a replica that matches those generated in pre-10.5.1 releases. These are designed to support syncing with lightweight mobile clients and have a single generation number (serverGen or replicaServerGen). A targetType of server generates a replica that supports syncing in one direction between two feature services running on servers or between an ArcGIS Server feature service and an ArcGIS Online feature service. When the targetType is server, the replica information includes a second generation number. This second generation number is called replicaServerSibGen for perReplica types and serverSibGen for perLayer types.

At 10.9, passing a request with the server value for this parameter, and the bidirectional syncDirection parameter value, enables bidirectional syncing. These values are only supported when the service's syncCapabilities object has the supportsBiDirectionalSyncForServer property set as true. Currently, this functionality 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. For more information, see Share content with collaboration groups.

A server targetType replicas generated with dataFormat SQLite can be published as new services in another ArcGIS Online organization or in ArcGIS Enterprise. When published, a replica is generated on these new services with a matching replicaID and a replicaServerSibGen or serverSibGens. The replicaServerSibGen or serverSibGens values can be used as the replicaServerGen or serverGen values when calling synchronize replica on the source service to get the latest changes. These changes can then be imported into the new service using the synchronizeReplica operation. When calling synchronizeReplica on the new service to import the changes, be sure to pass the new replicaServerGen or serverGen from the source service as the replicaServerSibGen or serverSibGen. This will update the replica metadata appropriately such that it can be used in the next sync.

NoteNote:

The targetType as well as the replicaServerSibGen or serverSibGen values are stored in the replica metadata, which can be accessed from the replicas resource.

Values: client | server

syncDirection

(Optional)

A syncDirection of bidirectional matches the functionality from replicas generated in pre-10.5.1 releases and allows upload and download of edits. It is only supported when targetType is client and, in some cases starting at 10.9, when targetType is server. When targetType is server, one way sync (which uses syncDirection upload and download) is always supported. A syncDirection of upload means that the synchronizeReplica operation allows only sync with an upload direction. Use this option to allow the upload of edits from the source service. A syncDirection of download means that the synchronizeReplica operation allows only sync with a download direction. Use this option to allow the download of edits to provide to the source service.

At 10.9, passing a request with the bidirectional value for this parameter, and the server targetType parameter value, enables bidirectional syncing. These values are only supported when the service's syncCapabilities object has the supportsBiDirectionalSyncForServer property set as true. Currently, this functionality 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. For more information, see Share content with collaboration groups.

This parameter defaults to bidirectional when the targetType is client and download when the targetType is server.

See the targetType parameter for more information.

NoteNote:

The syncDirection values are stored in the replica metadata which can be accessed from the replicas resource.

Values: bidirectional | upload | download

datumTransformations

(Optional)

Introduced at 10.8. This parameter applies a datum transformation on each layer when the spatial reference used in geometry is different than the layer's spatial reference. This parameter is a list of datum transformations. For each layer, if one of the transformations in the list is applicable with the layer's geometry, the transformation will be applied. For a list of valid datum transformation ID values ad well-known text strings, see Coordinate systems and transformations (values applicable for ArcGIS Desktop, ArcGIS Enterprise, ArcGIS Pro, and ArcGIS Runtime).

NoteNote:

It is possible to have less items listed in datumTransformations than the number of feature classes. The service will apply the first appropriate datum transformation it finds in the parameter. If no appropriate datum transformation, it will use the authored one from the map. If no transformation has been authored, the default value will be used.

Syntax

datumTransformations=[wkid1 | <dt1>, wkid2 | <dt2>,...]
datumTransformations{<dt1>,<dt2>...}

Examples

//to apply a simple transformation on each layer
datumTransformations=[1623, 1095]

//to apply a composite transformation on each layer
datumTransformations=[
  {
    "geoTransforms": [
      {"wkid": 1088, "transformForward": true},
      {"wkid": 1622, "transformForward": false}
    ]
  }
]
timeReferenceUnknownClient

Setting timeReferenceUnknownClient as true indicates 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.

NoteNote:

ArcGIS Pro 2.7 or newer can work with these feature services.

Value: true | false

f

The response format. The default format is html.

Values: html | json | pjson

syncDataOptions property values

This section describes the syncDataOptions values that can be provided with the replicaOptions parameter.

Annotation and dimensions

The syncDataOptions values that are needed to include annotation or dimensions layers are as follows:

  • {"syncDataOptions": 1}: Includes annotation feature layers.
  • {"syncDataOptions": 2}: Includes dimension feature layers.
  • {"syncDataOptions": 32}: Includes annotation feature layers with full model (added at 10.9).

Either value 1 or 33 can be used to add standard or feature-linked annotation layers to the replica.

Value 1 is more appropriate for clients that do not support the full high quality annotation data model. When 1 is used, the synchronization process will apply behavio2r for edits involving feature-linked annotation. For example, if the layer has feature-linked annotation, during sync upload the annotation will be generated on the service for feature inserts.

Value 33 should be used by clients that support the full high-quality annotation data model, such as ArcGIS Pro. This value is a combination of 1 (includes annotation) and 32, making it full model annotation. In this case, feature-linked annotation behavior is not applied on the server during sync, as clients are expected to provide the high-quality annotation edits. An exception to this would be when the replica includes a layer that has feature-linked annotation, but the annotation is not added to the replica. In that case, feature-linked annotation behavior is applied on the server as the client does not have annotations to send.

Dimension layers are included with value 2. These layers function similarly to standard annotation layers where edits are applied on sync without additional behavior.

Contingent values

Contingent values are included with {"syncDataOptions": 4}.

Even though contingent values will be included, they are not updated when the service is synced. Any violations resulting from incorrect contingent values will be caught during the validation process on the service, not during the sync process.

Utility networks

A subset of Utility Network system information is included with syncDataOptions 16. The subset includes the Utility Network layer metadata, associations, rules, and subnetworks. This option is used by clients for workflows that require visualizing utility networks in the field with associations. It will not include network topologies, network diagrams, or support for tracking offline.

The following example demonstrates setting syncDataOptions with value 16 and including the data from all layers. The layers in this example are:

List of Utility Network layers and tables that will be included as input for the
NoteNote:

Layer 8 is a Utility Network layer

The Utility Network system layers are as follows:

List of all Utility Network system layers that will be included as input for the

The required createReplica parameter values, using the Utility Network layers and system layer information, that can be passed in the request are outlined below:

layers=[0,1,2,3,4,5,6,7,8,10,11,12,13,500001,500002,500003]

layerQueries={"0":{"queryOption": "all", "useGeometry": false},
"1":{"queryOption": "all", "useGeometry": false},
"2":{"queryOption": "all", "useGeometry": false},
"3":{"queryOption": "all", "useGeometry": false},
"4":{"queryOption": "all", "useGeometry": false},
"5":{"queryOption": "all", "useGeometry": false},
"6":{"queryOption": "all", "useGeometry": false},
"7":{"queryOption": "all", "useGeometry": false},
"10":{"queryOption": "all", "useGeometry": false},
"11":{"queryOption": "all", "useGeometry": false},
"12":{"queryOption": "all", "useGeometry": false},
"13":{"queryOption": "all", "useGeometry": false},
"500001":{"queryOption": "all", "useGeometry": false},
"500002":{"queryOption": "all", "useGeometry": false},
"500003":{"queryOption": "all", "useGeometry": false}}

Geometry={"xmin": 6801882.314009005,"ymin": 1833711.8672784641,"xmax": 6818205.939993581,"ymax": 1854497.4691263959}

replicaOptions={"syncDataOptions":16}

async=true

At this release, another bit (syncDataOptions set as 128) can be set along with syncDataOptions as 16:

{“syncDataOptions”: 144}

This is supported when the service-level syncDataOptionsIncludeMissingUtilityNetworkLayers property is 128 and the service-level syncDataOptionIncludeUtilityNetworkSystem property is 16. When set, this will include the utility network layer and system tables that were not included with the layers parameter. Missing system tables, which include Associations, Rules, and Subnetworks, are added to the replica with the queryOption is set to all. If a system table is already included in the layers parameter, it is added with the queryOption property that is set as part of the layerQueries parameter. All other layers that are part of the utility network, but not present in the layers parameter, are added with an empty schema (when queryOption is set as none).

Additional considerations when choosing 16 for syncDataOptions

  • Value 16 allows you to add Utility Network layers, as well as their associations, rules, and subnetwork system layers to the layers parameter. Other system layers are not supported with this option.
  • Only Utility Network version 4 (or higher) supports using 16 for syncDataOptions. An error is returned if this option is used with older versions of Utility Network.
  • If 16 is not used as the value for syncDataOptions, and if the submitted layers include a Utility Network layer, associations layer, rules layer, or subnetworks system layer, an error is returned. However, non-system utility network layers can be included and taken offline as simple features.
  • Advanced fillers can be applied to the associations, rules, and subnetworks system layers using the layerQueries parameter.
  • When syncDataOptions is 16, all utility network layers are typically included as together they make up the Utility Network data model.
  • If you plan to use value 16 with sync options that require replica tracking, you will need to run the enable replica tracking GP tool in ArcGIS Pro 2.7 (or higher) on the Utility Network data. This will enable replica tracking on the system layers. As of 10.9, replica tracking is required when:
    • The service is configured with Create a version for each downloaded Map.
    • The replica is created with a targetType of server and syncDirection of bidirectional.
  • The dirty area layer cannot be included in the replica, regardless of whether 16 is the value for syncDataOptions.
  • Preplanned workflows which use the registerExistingData replicaOption can be used with replicas generated by using value 16.
  • Synchronization supports uploading inserts, updates, and deletes to associations, as well as inserts and deletes to subnetworks, from client to server. Inserts, updates, and deletes to rules are not supported with sync uploads. Sync downloads from the server includes all edit types (inserts, updates, and deletes) made to associations, subnetworks, and rules within the definition of the replica.

True curves

At this release, setting syncDataOptions as 256 will preserve true curves. By default (when syncDataOptions as 256 is not used) features with curves are returned with the curves densified for both the Create and Synchronize replica operations. Clients that can work with true curves can use syncDataOptions as 256 when using this operation, which will result in the true curves being preserved when taking the data offline and returning edits from the server upon synchronization.

Example usage

Example one

Below is a sample POST request for createReplica when dataFormat is set to sqlite:

POST /webadaptor/rest/services/LandUser/FeatureServer/createReplica HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

replicaName=Marshes&layers=0&layerQueries={"0":{"where":"Type=5"}}&geometry={"xmin": -120.8, "ymin": 35.14, "xmax": -120.66, "ymax": 35.2}&geometryType=esriGeometryEnvelope&inSR=4326&replicaSR=&transportType=esriTransportTypeURL&returnAttachments=true&returnAttachmentsDataByUrl=true&attachmentSyncDirection=none&async=true&syncModel=perReplica&dataFormat=sqlite&replicaOptions=&targetType=client&syncDirection=&datumTransformations=&f=json

The above request uses the following parameters and values:

replicaName=Marshes&
layers=0&
layerQueries={"0":{"where":"Type=5"}}&
geometry={"xmin": -120.8, "ymin": 35.14, "xmax": -120.66, "ymax": 35.2}&
geometryType=esriGeometryEnvelope&
inSR=4326&
replicaSR=&
transportType=esriTransportTypeURL&
returnAttachments=true&
returnAttachmentsDataByUrl=true&
attachmentSyncDirection=none&
async=true&
syncModel=perReplica&
dataFormat=sqlite&
replicaOptions=&
targetType=client&
syncDirection=&
datumTransformations=&
f=json

Example two

Below is a sample POST request for createReplica when dataFormat is set to json:

POST /webadaptor/rest/services/LandUser/FeatureServer/createReplica HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

replicaName=Marine&layers=0&layerQueries={"0":{"where":"Type=2"}}&geometry={"xmin": -120.8, "ymin": 35.14, "xmax": -120.66, "ymax": 35.2}&geometryType=esriGeometryEnvelope&inSR=4326&replicaSR=&transportType=esriTransportTypeURL&returnAttachments=true&returnAttachmentsDataByUrl=true&attachmentsSyncDirection=none&async=false&syncModel=perReplica&dataFormat=json&replicaOptions&targetType=client&syncDirection=&datumTransformations=&f=pjson

The above request uses the following parameters and values:

replicaName=Marine&
layers=0&
layerQueries={"0":{"where":"Type=2"}}&
geometry={"xmin": -120.8, "ymin": 35.14, "xmax": -120.66, "ymax": 35.2}&
geometryType=esriGeometryEnvelope&
inSR=4326&
replicaSR=&
transportType=esriTransportTypeURL&
returnAttachments=true&
returnAttachmentsDataByUrl=true&
attachmentsSyncDirection=none&
async=false&
syncModel=perReplica&
dataFormat=json&
replicaOptions&
targetType=client&
syncDirection=&
datumTransformations=&
f=pjson

JSON Response syntax

Example one

When transportType is set to esriTransportURL, the file returned in the URL contains a JSON or a sqlite payload (as specified with the dataFormat parameter) with a syntax as follows:

{
  "transportType": "esriTransportTypeURL",
  "responseType": "<esriReplicaResponseTypeData | esriReplicaResponseTypeInfo>",
  "layerServerGens": [{"id": "<layerId>", "serverGen": "<serverGen>"}], //Added in 10.6.1
  "URL":"<url>"
}

Example two

When async is set to true, the request is processed as an asychronous job, and a URL that a client can visit to check the status of the job is returned:

{
  "statusUrl": "<url>"
}

The following is the syntax of the status resource:

{ 
  "transportType": "esriTransportTypeURL",
  "responseType": <esriReplicaResponseTypeData | esriReplicaResponseTypeInfo>,
  "replicaName": "<replicaName>", 
  "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>"
}

Example three

If transportType is set to esriTransportTypeEmbedded and dataFormat is set to json, a JSON object response is directly returned with the following syntax:

{
  "replicaName": "<replicaName>",
  "replicaID": "<replicaID>", // unique value that identifies the replica/server
  "transportType": "<esriTransportTypeUrl | esriTransportTypeEmbedded>", 
  "responseType": "<esriReplicaResponseTypeData | esriReplicaResponseTypeInfo>",
  "syncModel": "<perReplica | perLayer>",
  "layerServerGens": [
	   {"id": <layer1Id>,"serverGen":<genNum>},
	   {"id": <layer2Id,"serverGen":<genNum>}
	 ], // read only values for clients. Only if syncModel = perLayer
  "replicaServerGen: "<replicaServerGen>", // read only value for clients. Only if syncModel = perReplica
  "layers": [
    {
      "id": <layerId1>,
      "features": [ //features will include geometry for feature layers only
        <feature1>, <feature2> 
      ],
      "attachments": [ 
        "<attachment1>, <attachment2> 
      ]
    },
    {
      "id": <layerId2>,
      "features": [ //features will include geometry for feature layers only
        <feature1>, <feature2>
      ],
      "attachments": [ 
        "<attachment1>, <attachment2>
      ]
    }
  ]
}

JSON Response example

Example one

When async is set to true, the request is processed as an asynchronous job and a URL that a client can visit to check the status of the job is returned. The file returned in the resultURL is a sqlite geodatabase. The sqlite replica geodatabase contains the same information and data as the JSON file content in the subsequent example:

{  
   "statusUrl": "https://services.myserver.com/arcgis/rest/services/LandUse/FeatureServer/jobs/j0b4b6064db0f44e6b5f39c4ef301d1f9"
}

Response example for the status resource:

{ 
  "transportType": "esriTransportTypeUrl",
  "responseType": "esriReplicaResponseTypeData",
  "replicaName": "Soils",
  "replicaID": "99F979B0-A93A-4EBF-9015-D4FDB567218E",
  "targetType": "server",
  "resultUrl": "https://services.myserver.com/arcgis/rest/services/directories/replicafiles/_ags_data{422DCB2CDD8340A7B73639846E9AB43C}.geodatabase"
  "submissionTime": 1379366479000, 
  "lastUpdatedTime": 1379366482000, 
  "status": "Completed" 
}

Example two

When creating a replica with transportType set as esriTransportTypeUrl and dataFormat is set to sqlite, the response includes layerServerGens and a sqlite geodatabase:

{
  "transportType": "esriTransportTypeUrl",
  "responseType": "esriReplicaResponseTypeData",
  "layerServerGens": [
    {
      "id": 0,
      "serverGen": 1526605677436
    }
  ],
  "URL": "https://services.myserver.com/arcgis/rest/directories/arcgisoutput/Sync_MapServer/_ags_dataE00E0CEDE72B4526BBD3B659088FE365.geodatabase"
}

Example three

Where transportType is set to esriTransportTypeUrl and dataFormat is set to json:

{
  "transportType":"esriTransportTypeUrl", 
  "responseType": "esriReplicaResponseTypeData",
  "replicaName": "Meters", 
  "resultUrl":  "https://arcgis.com/lidGgNLxw9LL0SbI/ArcGIS/rest/services/SaveTheBay/replicafiles/c2f366ffbf5549a48727d2529b2c6ed5.json",   
  "submissionTime": 1379366479000, 
  "lastUpdatedTime": 1379366482000, 
  "status": "Completed"
}

The file content:

{
  "replicaName": "Marine", 
  "replicaID": "{5016655f-4db8-4745-b1ab-995081dfcb52}", 
  "layerServerGens": [
    {
      "id": 0, 
      "serverGen": 8411
    }
  ], 
  "responseType": "esriReplicaResponseTypeData", 
  "syncModel": "perLayer", 
  "layers": [
    {
      "id": 0, 
      "features": [
        {
          "geometry": {
            "x": -120.73650757099995, 
            "y": 35.165736219000053
          }, 
          "attributes": {
            "OBJECTID": 5, 
            "Type": 2, 
            "Confirmed": 0, 
            "Comments": "", 
            "creator": "user1", 
            "editor": "user1", 
            "Submitted": 1298911207000, 
            "GlobalID": "85e499ac-8bff-42e8-9897-12f121898565"
          }
        }, 
        {
           "geometry": {
             "x": -120.74290998099991, 
             "y": 35.157279059000075
          }, 
          "attributes": {
            "OBJECTID": 6, 
            "Type": 2, 
            "Confirmed": 0, 
            "Comments": "", 
            "creator": "user1", 
            "editor": "user1", 
            "Submitted": 1298911207000, 
            "GlobalID": "a699a609-8cbd-4a18-a363-42ac87e75e19"
          }
        }, 
        {
          "geometry": {
            "x": -120.73939627999994, 
            "y": 35.175259875000052
          }, 
          "attributes": {
            "OBJECTID": 1627, 
            "Type": 2, 
            "Confirmed": 0, 
            "Comments": "", 
            "creator": "user1", 
            "editor": "user1", 
            "Submitted": 1298652153000, 
            "GlobalID": "ed8e7ee8-4a91-4d5e-8bed-9f609c66387b"
          }
        }
      ], 
      "attachments" : [
      ]
    }
  ]
}

Example four

Where dataFormat is set to json and the data contains attachments:

{
  "transportType":"esriTransportTypeUrl", 
  "responseType":"esriReplicaResponseTypeData",
  "URL": "https://machinename:6443/arcgis/rest/directories/arcgisoutput/Canada/test113c26d11b80f049c09aef1e6c1327641c.json"
}

The file content:

{
  "replicaName": "ags_gfs_4",
  "replicaID": "D4B2D34C-61DD-4AED-BF37-B7AC363CDB08",
  "transportType": "esriTransportTypeUrl",
  "responseType": "esriReplicaResponseTypeData",
  "syncModel": "perReplica",
  "replicaServerGen": 0,
  "responseType": "esriReplicaResponseTypeData",
  "layers": [
    {
      "id": 0,
      "features": [
        {
          "geometry": {
            "x": -123.06999969499992,
             "y": 49.159999847000051
          },
          "attributes": {
            "OBJECTID": 1,
            "NAME": "Vancouver",
            "CAPITAL": "N",
            "PROV_NAME": "British Columbia",
            "GLOBALID": "{C74D42DB-5D07-4AB8-8C91-11AE1E52E6A3}",
            "POPULATION_DOMAIN": 4,
            "RepRowID": 1
          }
        },
        {
          "geometry": {
            "x": -114.05000305199991,
            "y": 51.029998779000039
          },
          "attributes": {
            "OBJECTID": 2,
            "NAME": "Calgary",
            "CAPITAL": "N",
            "PROV_NAME": "Alberta",
            "GLOBALID": "{6A33F63A-AA90-4970-AB76-76B32E702745}",
            "POPULATION_DOMAIN": 5,
            "RepRowID": 2
          }
        },
        {
          "geometry": {
            "x": -113.27999877899992,
            "y": 53.330001831000061
          },
          "attributes": {
            "OBJECTID": 3,
            "NAME": "Edmonton",
            "CAPITAL": "Y",
            "PROV_NAME": "Alberta",
            "GLOBALID": "{4D809477-4994-4B8C-80E7-1631E0AD3FA9}",
            "POPULATION_DOMAIN": 4,
            "RepRowID": 3
          }
        },
        {
          "geometry": {
            "x": -97.124443053999926,
            "y": 49.921169281000061
          },
          "attributes": {
            "OBJECTID": 4,
            "NAME": "Winnipeg",
            "CAPITAL": "Y",
            "PROV_NAME": "Manitoba",
            "GLOBALID": "{CDB3FD57-2E2A-4FBF-998D-B84E5E26167D}",
            "POPULATION_DOMAIN": 3,
            "RepRowID": 4
          }
        },
        {
          "geometry": {
            "x": -75.650749206999933,
            "y": 45.374221802000079
          },
          "attributes": {
            "OBJECTID": 6,
            "NAME": "Ottawa",
            "CAPITAL": "C",
            "PROV_NAME": "Ontario",
            "GLOBALID": "{0F2F8880-4763-481A-9379-62B573ED3154}",
            "POPULATION_DOMAIN": 4,
            "RepRowID": 6
          }
        },
        {
          "geometry": {
            "x": -73.653526305999947,
            "y": 45.541019440000071
          },
          "attributes": {
            "OBJECTID": 7,
            "NAME": "Montreal",
            "CAPITAL": "N",
            "PROV_NAME": "Quebec",
            "GLOBALID": "{BE529DB3-D879-476F-B3CA-FF4E9B32A36B}",
            "POPULATION_DOMAIN": 6,
            "RepRowID": 7
          }
        },
        {
          "geometry": {
            "x": -71.244926452999948,
            "y": 46.802070618000073
          },
          "attributes": {
            "OBJECTID": 8,
            "NAME": "Quebec",
            "CAPITAL": "Y",
            "PROV_NAME": "Quebec",
            "GLOBALID": "{99FD4EF2-4548-4FD6-97A4-CAC6B3185373}",
            "POPULATION_DOMAIN": 3,
            "RepRowID": 8
          }
        },
        {
          "geometry": {
            "x": -123.34989929199992,
            "y": 48.451988220000032
          },
          "attributes": {
            "OBJECTID": 9,
            "NAME": "Victoria",
            "CAPITAL": "Y",
            "PROV_NAME": "British Columbia",
            "GLOBALID": "{8F558B76-98E1-41AE-92D0-148547E344A6}",
            "POPULATION_DOMAIN": 2,
            "RepRowID": 9
          }
        }
      ],
      "attachments": [
        {
          "attachmentId": 2,
          "globalId": "{A8AFEC66-516B-40E9-9BAC-2F26AB0E0253}",
          "parentGlobalId": "{C74D42DB-5D07-4AB8-8C91-11AE1E52E6A3}",
          "contentType": "application/pdf",
          "size": 762519,
          "name": "celebrate_CND.pdf",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach1c2b660372a64876944b1e874c930b3f.pdf"
        },
        {
          "attachmentId": 3,
          "globalId": "{B5B41B49-73C4-48C1-A5B0-4DFDDCA73F25}",
          "parentGlobalId": "{C74D42DB-5D07-4AB8-8C91-11AE1E52E6A3}",
          "contentType": "image/jpeg",
          "size": 35277,
          "name": "vancouver.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach83633fbcc78e400cbe669f16700d467f.jpg"
        },
        {
          "attachmentId": 4,
          "globalId": "{4E430844-01C2-41F5-A540-B9BE97A0D187}",
          "parentGlobalId": "{8F558B76-98E1-41AE-92D0-148547E344A6}",
          "contentType": "image/jpeg",
          "size": 4424,
          "name": "rockies.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach54cc055852e64c589b5cd60b51ee4645.jpg"
        },
        {
          "attachmentId": 5,
          "globalId": "{E71B2FC1-1173-424E-9B01-57B6FD2CBCD6}",
          "parentGlobalId": "{8F558B76-98E1-41AE-92D0-148547E344A6}",
          "contentType": "image/jpeg",
          "size": 18813,
          "name": "novascotia.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach80bea2ecd080460cbe6155fa1ec79532.jpg"
        },
        {
          "attachmentId": 6,
          "globalId": "{CB299B1F-736D-4080-B01E-C07B1B6ABA88}",
          "parentGlobalId": "{6A33F63A-AA90-4970-AB76-76B32E702745}",
          "contentType": "image/jpeg",
          "size": 52568,
          "name": "mountains.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach60fbca550b944f4b855f2fb1f0375955.jpg"
        },
        {
          "attachmentId": 7,
          "globalId": "{5B2D5F6C-8495-4BB4-9D09-B4DA9EE8D3B9}",
          "parentGlobalId": "{4D809477-4994-4B8C-80E7-1631E0AD3FA9}",
          "contentType": "application/pdf",
          "size": 84256,
          "name": "cnd_doc.pdf",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach8bffd96db040439694bde39b23f8f392.pdf"
        },
        {
          "attachmentId": 24,
          "globalId": "{17686592-E726-40F0-8B73-2168C7543E43}",
          "parentGlobalId": "{BE529DB3-D879-476F-B3CA-FF4E9B32A36B}",
          "contentType": "image/jpeg",
          "size": 4424,
          "name": "rockies.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach981c1c88d9194ac3b6382b67f410d629.jpg"
        },
        {
          "attachmentId": 25,
          "globalId": "{998ECBE2-6D27-4244-82A2-5E05D7A6655D}",
          "parentGlobalId": "{BE529DB3-D879-476F-B3CA-FF4E9B32A36B}",
          "contentType": "image/jpeg",
          "size": 118371,
          "name": "politics.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach9093c7c9ea9748f0a5b41a2972a8db0e.jpg"
        },
        {
          "attachmentId": 29,
          "globalId": "{913DCE0B-0655-410C-8697-95EB872F2EA8}",
          "parentGlobalId": "{0F2F8880-4763-481A-9379-62B573ED3154}",
          "contentType": "image/jpeg",
          "size": 52568,
          "name": "mountains.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach6c2bb62d0c1d43ff8810c2485ca5e21b.jpg"
        },
        {
          "attachmentId": 30,
          "globalId": "{E39194E1-A2B5-4920-9BB2-1189EA5E5FA4}",
          "parentGlobalId": "{0F2F8880-4763-481A-9379-62B573ED3154}",
          "contentType": "image/jpeg",
          "size": 19530,
          "name": "polarbear_cub.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach55256b8ad9724574a17c47f960959cc1.jpg"
        },
        {
          "attachmentId": 31,
          "globalId": "{C7BF62B1-D8DB-4ECD-ACB7-42BEC64DB59B}",
          "parentGlobalId": "{0F2F8880-4763-481A-9379-62B573ED3154}",
          "contentType": "image/jpeg",
          "size": 118371,
          "name": "politics.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach9dc1d884ed0e45e0b1ea1a2ef96f17e4.jpg"
        },
        {
          "attachmentId": 32,
          "globalId": "{CAD4BFAA-F6D6-43A5-8594-DCA86C468F88}",
          "parentGlobalId": "{99FD4EF2-4548-4FD6-97A4-CAC6B3185373}",
          "contentType": "image/jpeg",
          "size": 118371,
          "name": "politics.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attachd807f2238bf04074836a3e2648bb740d.jpg"
        },
        {
          "attachmentId": 33,
          "globalId": "{21A265D7-87BE-4C46-B59F-FBFF5FE8A533}",
          "parentGlobalId": "{99FD4EF2-4548-4FD6-97A4-CAC6B3185373}",
          "contentType": "image/jpeg",
          "size": 28588,
          "name": "flag.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach27740a4f7c4d422a893a6c263bd79575.jpg"
        },
        {
          "attachmentId": 34,
          "globalId": "{FF4E9E9E-BC4C-48F5-B2DA-EA9D243EB6B3}",
          "parentGlobalId": "{99FD4EF2-4548-4FD6-97A4-CAC6B3185373}",
          "contentType": "image/jpeg",
          "size": 69583,
          "name": "highway.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attachc225fced338547cf81f0f6eb575e60e8.jpg"
        },
        {
          "attachmentId": 35,
          "globalId": "{1C6F43AD-68F7-4C27-A683-639D7B973909}",
          "parentGlobalId": "{99FD4EF2-4548-4FD6-97A4-CAC6B3185373}",
          "contentType": "image/jpeg",
          "size": 52568,
          "name": "mountains.jpg",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach31d77279e58e4fec8cc3c6f30a714bb5.jpg"
        },
        {
          "attachmentId": 48,
          "globalId": "{90234EC7-0D60-4178-993A-0D132E63A9EF}",
          "parentGlobalId": "{CDB3FD57-2E2A-4FBF-998D-B84E5E26167D}",
          "contentType": "application/pdf",
          "size": 331959,
          "name": "CND_goose.pdf",
          "url": "https://myserver:6443/arcgis/rest/directories/arcgisoutput/Canada/_ags_fsRep_attach6b4143202a1445ac81f1218b9b28c503.pdf"
        }
      ]
    }
  ]
}
Copyright © 1995-2022 Esri. All rights reserved.