Create Replica

Description: The response format. The default response format is html.

Values: html | json

Description: The name of the replica on the server. The replica name is unique per feature service.

This is not a required parameter. 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

Description: (Required) The list of layers and tables to include in the replica.

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

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

Example: layers=0, 1, 2

layers=[0, 1, 2]

Description: In addition to the layers and geometry parameters, the layerQueries parameter can be used to further define what is replicated. This parameter allows you to set properties on a per-layer or per-table basis. 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: {.}}

Examples:

• A service has a facilities layer (id=0) and inspection layer (id=1), and they are related. To replicate facilities in an area that needs inspection:

  layerQueries = {"0":{"queryOption": "useFilter", "useGeometry": true, "where": "requires_inspection = Yes"}}

• To 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}}

• To replicate all aircraft in a layer:

  layerQueries = {"2":{"queryOption": "all"}}

• To replicate all international aircraft:

  layerQueries = { "2":{"queryOption": "useFilter", "useGeometry": false, "where": "international= true" }}

• To only upload a device's GPS tracks and not get any tracks back:

  layerQueries ={"3":{"queryOption": "none", "includeRelated": false}}

Description: (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>

Examples:

• geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}
• geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41
• geometryType=esriGeometryPoint&geometry=-104,35.6

Description: 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 envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

Description: 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.

Description: 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.

Description: The transportType represents the response format. If the transportType is 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.

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

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

Values: true | false

Description: 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. This parameter is only applicable if the feature service has attachments and if returnAttachments is true and f=json.

Values: true | false

This option was added at 10.4. This parameter is available when the service resource syncCapabilities property includes "supportsAttachmentsSyncDirection" : true

Description: 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.

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.

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

Values: bidirectional | upload | none

Description: If true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job. See the topic on asynchronous usage for more information. The default is false.

Values: true | false

Description: 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=none can be used to export the data without creating a replica. Query the supportsSyncModelNone property of the feature service to see if this model type is supported.

See the RollbackOnFailure and Sync Models topic for more details.

Values: perReplica | perLayer | none

Example: syncModel=perLayer

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

Note:

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

Syntax: sqlite | filegdb| shapefile | json

Example: dataFormat=sqlite

Description: 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.

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

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.

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.

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.

Note:

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>}]}}

Examples:

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

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

To use replicaOptions to include layers that are not of "type": "feature layer" or "type": "table" in the replica, it must include the syncDataOptions property. The syncDataOptions property can be included if the service supportedSyncDataOptions property is set. Possible layer types that may be include are as follows:

• {"syncDataOptions": 1} is specified to include annotation feature layers.
• {"syncDataOptions": 2} is specified to include dimension feature layers.
• {"syncDataOptions": 4} is specified to include contingent values.

To include multiple syncDataOptions in the replica, the values can be added together. For example, to include annotation and dimension feature layers, {"syncDataOptions": 3}. To include all three, {"syncDataOptions": 7}.

The value of the supportedSyncDataOptions property indicates the layer types available in the service. For example, “supportedSyncDataOptions”: 3 indicates that there is at least one annotation and one dimension layer in the service.

Note:

• Even though contingent values will be included in the replica when specified, they will not be updated when sync is performed on the service. Any violations resulting from incorrect contingent values will be caught during the validation process and not during the sync process.
• {"syncDataOptions": 0} will be treated the same as if the parameter was not passed.

Syntax:

replicaOptions = {"syncDataOptions": <syncDataOptions>}

Example:

replicaOptions = {"syncDataOptions": 4}

targetType

This option was added at 10.5.1.

Description: Can be set to either server or client. If not set, the default is client.

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.

targetType server 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.

Note:

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

Example: targetType=server

Description: Defaults to bidirectional when the targetType is client and download when the targetType is server. If set, only bidirectional is supported when targetType is client. If set, only upload or download are supported when targetType is server.

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.

When targetType is server, only a one way sync is supported; thus, only upload or download are valid options.

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.

See the targetType parameter for more information.

Note:

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

Example: syncDirection=download