ArcGIS REST API - ArcGIS Services

URL:http://<featureservice-url>/createReplica(POST only)
Required Capability:Create, Update, Delete,Sync
Version Introduced:10.0

Description

The createReplica operation is performed on a feature service resource. This operation creates the replica between the feature service and a client based on a client-supplied replica definition. It requires the Sync capability. See Sync overview for more information on sync.

The response for createReplica includes replicaID, server generation number, and data similar to the response from the feature service query operation.

The createReplica operation returns a response of type esriReplicaResponseTypeData, as the response has data for the layers in the replica. If the operation is called to register existing data by using replicaOptions, the response type will be esriReplicaResponseTypeInfo, and the response will not contain data for the layers in the replica.

For detailed examples, see the Sync workflow examples topic.

You can provide arguments to the createReplica operation as defined in the following parameters table:

Request parameters

Parameter	Details
f	Description: The response format. The default response format is html. Values: html \| json
replicaName	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
layers	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]
layerQueries	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 or not to apply the geometry for the layer. The default is true. If set to false, features from the layer that intersect the geometry are not added. includeRelated—Determines whether or not 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}}
geometry	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
geometryType	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
inSR	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.
replicaSR	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.
transportType	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
returnAttachments	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
returnAttachmentsDatabyURL	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
attachmentsSyncDirection	This option is new 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: 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, create replica includes attachments from the service. When returnAttachments is set to false, you can set attachmentsSyncDirection to either upload or none (default). In this case, create replica 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
async	Description: If true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job. See the topic on asynchronous usage for more information. The default is false. Values: true \| false
syncModel	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
dataFormat	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 \| json Example: dataFormat=sqlite
replicaOptions	Description: This parameter instructs the createReplica operation to create a new replica based on an existing replica definition (refReplicaId). It can be used to specify parameters for registration of existing data for sync. 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 number(s). 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. The value of refReplicaServerGen is ignored if the layers on the server are versioned (layer property: isDataVersioned = true). When replicaOptions are set with versioned data, it is assumed that the client has the most recent copy of the data. 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}]}}

Example usage

createReplica request URL for dataFormat=sqlite

Request URL:

http://services.myserver.com/ERmEceOGq5cHrItq/ArcGIS/rest/services/LandUse/FeatureServer/createReplica

POST parameters:

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

createReplica request URL for dataFormat=json

Request URL:

http://services.myserver.com/ERmEceOGq5cHrItq/ArcGIS/rest/services/SaveTheBay/FeatureServer/createReplica

POST parameters:

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

JSON response syntax (transportType=esriTransportTypeUrl)

When transportType=esriTransportTypeUrl, 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>",
  "URL":"<url>"
}

JSON response syntax (async=true and transportType=esriTransportTypeUrl )

When async=true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job.

            
          
{
  "statusUrl": "<url>"
}

JSON syntax of status resource:

{ 
  "transportType": "esriTransportTypeURL",
  "responseType": <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>"

}

JSON response syntax (written to a JSON file)

If transportType=esriTransportTypeEmbedded and dataFormat=json, a JSON object response is directly returned as follows:

            
          
{
  "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 (async=true and dataFormat=sqlite)

When async=true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job. 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": "http://services.myserver.com/arcgis/rest/services/LandUse/FeatureServer/jobs/j0b4b6064db0f44e6b5f39c4ef301d1f9"
}

Content of the status resource:

            
          
{ 
   "transportType": "esriTransportTypeUrl",
   "responseType": "esriReplicaResponseTypeData",
   "replicaName": "Soils", 
   "resultUrl": "http://services.myserver.com/arcgis/rest/services/directories/replicafiles/_ags_data{422DCB2CDD8340A7B73639846E9AB43C}.geodatabase"
   "submissionTime": 1379366479000, 
   "lastUpdatedTime": 1379366482000, 
   "status": "Completed" 
}

JSON response example (transportType=esriTransportTypeUrl and dataFormat=json)

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

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" : [
      ]
    }
  ]
}

JSON response example (data contains attachments [dataFormat=json])

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