ArcGIS REST API - ArcGIS Services - Extract Changes (Feature Service)

URL:http:// <catalog-url>/<serviceName>/FeatureServer/extractChanges(POST only)

Description

Feature service change tracking is an efficient change tracking mechanism for applications. Applications can use change tracking to query changes that have been made to the layers and tables in the service. For enterprise geodatabase based feature services published from ArcGIS Pro 2.2 or higher, the ChangeTracking capability requires all layers and tables to be either archive enabled or branch versioned and have globalid columns. Change tracking can also be enabled for ArcGIS Online hosted feature services. If all layers and tables in the service have the ChangeTracking capability, the extractChanges operation can be used to get changes.

Check the sub-properties of extractChangesCapabilities on the service resource to see which extractChanges options are supported. These include:

supportsReturnIdsOnly - allows the use of the returnIdsOnly parameter which returns only the IDs of the features that were changed.
supportsReturnExtentOnly - allows the use of the returnExtentOnly parameter to return the extent of the changed features.
supportsReturnAttachments - allows the use of the returnAttachments parameter. This will return any attachments associated with the changed features.
supportsLayerQueries - allows the use of layerQueries to limit the changed features returned using filters such as a where clause.
supportsGeometry - allows the use of the geometryparameter which will return changed features within a defined geometry.
supportsReturnFeature - will allow full rows to be returned for updates or inserts as opposed to IDs only.

Note:

All properties listed within the extractChangesCapabilities can be true or false.

For 10.6.1 enterprise geodatabase based feature services published from ArcGIS Pro 2.2, supportsReturnIdsOnly is the only sub-property set to true. This allows you to use the extractChanges operation to retrieve the objectids of the inserts, updates, and/or deletes that have happened since a specific time period.

Enable and disable change tracking

Feature service change tracking capability must be enabled in order to track layer changes. When change tracking is enabled, change tracking information is maintained for all rows in the layers and tables that are affected by any editing or sync operation.

To enable or disable change tracking on an existing feature service, add or remove the ChangeTracking capability to or from the feature service.

A feature service with change tracking enabled returns the following additional metadata. layerSrverGens in changeTrackingInfo needs to be cached on the client. The client needs to pass change layerServerGens to the server when requesting the latest changes from the server.

{"capabilities" : "Create,Delete,Query,Update,Editing,ChangeTracking"}
"changeTrackingInfo" : { "lastSyncDate" : 1519247516232, "layerServerGens" : [ { "id" : 0, "minServerGen" : 1529667, "serverGen" : 1534028 } ] },

Note:

Currently in 10.6.1, enterprise geodatabase based feature services do not support enabling and disabling the ChangeTracking capability. ChangeTracking will automatically be enabled on the geodatabase based feature service if the data is archive enabled or is branch versioned and has globalid columns.

Hosted Feature Service Views

The ChangeTracking service capability can be enabled or disabled on a feature service view if its source feature service has ChangeTracking enabled. ChangeTracking capability cannot be disabled on a source feature service if any of it's views have ChangeTracking enabled.

hasChangeTrackingEnabledViews service property

Source feature service with views or map/tile service with change tracking enabled will return "hasChangeTrackingEnabledViews" : true in the metadata. This would allow the UX to block user from disabling change tracking on a source feature service when its views have also change tracking enabled. This is a computed property and will be changed when the source feature service views change tracking is enabled or disabled or when views or map services are deleted.

Request Parameters


Parameter	Details
layers	Description: (Required) The list of layers and tables to include in the replica. Syntax: layers = [<layer1>, <layer2>, <table1>] Example: layers = 0,1,2 or layers = [0,1,2] Note: Currently, geodatabase based feature service only support layer = [0,1,2] syntax.
layerQueries	Description: In addition to the layers and geometry parameters, the layerQueries parameter can be used to further define what changes to return. This parameter allows you to set query properties on a per-layer or per-table basis. If a layer's ID is present in the layers parameter and missing from layerQueries, it's changed 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 defualt is true. The 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. queryOptoin-Defines whether or how filters will be applied to a layer. The queryOption was added in 10.2. See the Compatibility notes topic for more information. Values: <none \| useFilter \| all> When is value is none, no feature 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 returned. The value of includeRelated is 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: Syntax: layerQueries = {"0":{"queryOption": "useFilter", "useGeometry": true, "where": "requires_inspection = yes"}} To replicate facilities in an area that needs inspection and their related inspections: Syntax: layerQueries = {"0":{"queryOption": "useFilter", "useGeometry": true, "where": "requeires_instpection = yes"}, {"1":{"queryOption": "none", "includedRelated": true}} To replicate all aircraft in a layer: Syntax: layerQueries = {"2":{"queryOption": "all"} To replicate all international aircraft: Syntax: layerQueries = {"2":{"queryOption": "sueFilter", "useGeometry": false, "where": "international=true"}} To only upload a device's GPS tracks and not get any tracks back: Syntax: layerQueries = {"3":{"queryOption": "none", "includeRelated": false}}
geometry	Description: The geometry to apply as the spatial filter for the changes. All the changed features in layers intersecting this geometry will be returned. 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} Envelopes simple syntax: geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax> Point simple syntax: geometryType=esriGeometryPoint&geomtry=<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
geomtryType	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 asa 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 the inSR is not specified, the geometry is assumed to be in the special reference of the map.
outSR	Description: The output spatial reference of the returned changes. 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-know ID (wkid) or well-known text (wkt). If the outSR is not specified, the data changes will be returned in the spatial reference of the feature service.
gdbVersion	This option can only be used with branch versioned data. Description: The geodatabase version name. This parameter applies only if the hasVersionedData property of the service and the isDataVersioned property of the layer(s) are true. If gdbVersion is not specified, the query will apply to the published map's version. Values: gdbVersion = <version> Example: gdbVersion = admin.version1
returnInserts	Description: If true, newly inserted features will be returned. The default is false. Values: true \| false
returnUpdates	Description: If true, updated features will be returned. The default is false. Values: true \| false
returnDeletes	Description: If true, deleted features will be returned. The default is false. Values: true \| false
layerServerGens	Description: (Required) The layerServerGen allows a client to specify the last layer generation numbers for the changes received from the server. minServerGen: It is the min generation of the server data changes. clients with layerServerGens that is less than minServerGen cannot extract changes and would need to make a full server/layers query instead of extracting changes. serverGen: It is the current server generation number of the changes. Every changed feature has a version or a generation number that is changed every time the feature is updated. Syntax: "layerServerGen": [{"id": <layerId1>, "serverGen": <genNum1>}, {"id": <layerId2>, "serverGen": <genNum2>}] Example: "layerServerGen": [{"id": 0, "serverGen": 10500}, {"id": 1, "serverGen": 1100}, {"id": 2, "serverGen": 1200}]
returnIdsOnly	Description: If true, the response includes an array of object IDs only. The default is false. Value: true \| false
returnExtentOnly	Description: If true, only the extent of the changes will be returned. The default is false. Value: true \| false
returnAttachments	Description: If true, attachments changes are 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. 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. Value: true \| false
dataFormat	Description: The format of the changes returned in the response. The default is json. Syntax: sqllite \| json Example: dataFormat=sqllite
changesExtentGridCell	Description: To optimize localizing changes extent, the value medium is an 8x8 grid that bound the changes extent. Used only when returnExtentOnly is true. The default is none. Values: none \| large \| medium \| small
f	Description: The response format. The default value is html. Values: html \| json

Example Usage

Steps:

Enable the feature service change tracking if it is not enabled.
http://services.myserver.com/<tenant>/ArcGIS/rest/admin/services/USA/FeatureServer/updateDefinition
{"capabilities" : "Create,Delete,Query,Update,Editing,ChangeTracking,Sync" }
Get the feature service metadata with returnUpdates=true.
http://services.myserver.com/<tenant>/ArcGIS/rest/services/USA/FeatureServer?f=pjson&returnUpdates=true
Cache the following layerServerGens json object in the client side.
{ "layerServerGens" : [ { "id" : 0, "minServerGen" : 1529667, "serverGen" : 1534028 } ] }
Call extractChanges API and pass the server layerSrverGens and any filtering criteria.
Update the client cached layerServerGens json object from the extractChanges response in (4).
Continue in steps 4-6.

Example 1: Extract Changes - Features (Inserts + Updates + Deletes)

Parameters:

layers=0

returnInserts=true

returnUpdates=true

returnDeletes-true

layerServerGens= [ { "id" : 0, "minServerGen" : 1529667, "serverGen" : 1534028 } ] }

dataFormat=json

JSON Response Example

{  
   "layerServerGens":[  
      {  
         "id":0,
         "serverGen":153025
      }
   ],
   "transportType":"esriTransportTypeUrl",
   "responseType":"esriDataChangesResponseTypeEdits",
   "edits":[  
      {  
         "id":0,
         "features":{  
            "adds":[  
               {  
                  "geometry":{  
                     "rings":[  
                        [  
                           [  
                              1599093.38156825,
                              4299494.38162189
                           ],
                           [  
                              1621892.61012839,
                              4282639.631925
                           ],
                           [  
                              1616369.15773174,
                              4273287.47109171
                           ],
                           [  
                              1596005.6876463,
                              4284510.52152801
                           ],
                           [  
                              1599093.38156825,
                              4299494.38162189
                           ]
                        ]
                     ]
                  },
                  "attributes":{  
                     "FID":250,
                     "GlobalID":"C8FCEBF0-51D1-4FFA-A5ED-FFD47F10014F",
                     "ObjectID":125,
                     "FIPS_CNTRY":"MT",
                     "GMI_CNTRY":"MLT",
                     "ISO_2DIGIT":"MT",
                     "ISO_3DIGIT":"MLT",
                     "ISO_NUM":470,
                     "CNTRY_NAME":"Malta",
                     "LONG_NAME":"Republic of Malta",
                     "ISOSHRTNAM":"Malta",
                     "UNSHRTNAM":"Malta",
                     "LOCSHRTNAM":"Malta",
                     "LOCLNGNAM":"Repubblika ta' Malta",
                     "STATUS":"UN Member State",
                     "POP2007":401880,
                     "SQKM":211.5,
                     "SQMI":81.66,
                     "LAND_SQKM":316,
                     "COLORMAP":2
                  }
               }
            ],
            "updates":[  
               {  
                  "geometry":{  
                     "rings":[  
                        [  
                           [  
                              1599093.38156825,
                              4299494.38162189
                           ],
                           [  
                              1621892.61012839,
                              4282639.631925
                           ],
                           [  
                              1616369.15773174,
                              4273287.47109171
                           ],
                           [  
                              1596005.6876463,
                              4284510.52152801
                           ],
                           [  
                              1599093.38156825,
                              4299494.38162189
                           ]
                        ]
                     ]
                  },
                  "attributes":{  
                     "FID":1,
                     "GlobalID":"CECC5D06-CFD4-40E7-943B-3793770411E1",
                     "ObjectID":125,
                     "FIPS_CNTRY":"MT",
                     "GMI_CNTRY":"MLT",
                     "ISO_2DIGIT":"MT",
                     "ISO_3DIGIT":"MLT",
                     "ISO_NUM":470,
                     "CNTRY_NAME":"Malta",
                     "LONG_NAME":"Republic of Malta",
                     "ISOSHRTNAM":"Malta",
                     "UNSHRTNAM":"Malta",
                     "LOCSHRTNAM":"Malta",
                     "LOCLNGNAM":"Repubblika ta' Malta",
                     "STATUS":"UN Member State",
                     "POP2007":401880,
                     "SQKM":211.5,
                     "SQMI":81.66,
                     "LAND_SQKM":316,
                     "COLORMAP":2
                  }
               }
            ],
            "deleteIds":[  
               "0D8E1D93-29AE-4D16-AF61-E74FED983732"
            ]
         }
      }
   ]
}

JSON response example (with returnIdsOnly = true, returnInserts = true, returnUpdates = true, and returnDeletes = true)

{
 "layerServerGens": [
  {
   "id": 0,
   "serverGen": 1526588581400
  },
  {
   "id": 1,
   "serverGen": 1526588581553
  }
 ],
 "edits": [
  {
   "id": 0,
   "objectIds": {
    "adds": [
     2027,
     2028,
     2029
    ],
    "updates": [2026],
    "deletes": []
   }
  },
  {
   "id": 1,
   "objectIds": {
    "adds": [
     27971,
     27972
    ],
    "updates": [],
    "deletes": [
     27189,
     27970
    ]
   }
  }
 ]
}