Extract Changes (Feature Service)

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 later, 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 subproperties of extractChangesCapabilities on the service resource to see which extractChanges options are supported. These include the following:

NoteNote:

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 subproperty set to true. This allows you to use the extractChanges operation to retrieve the objectids of the inserts, updates, and deletes that have happened since a specific time period.

Enable and disable change tracking

The feature service change tracking capability must be enabled 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 must 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 } ] },
NoteNote:

At 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 its views have ChangeTracking enabled.

hasChangeTrackingEnabledViews service property

Source feature services with views or map/tile service with change tracking enabled will return "hasChangeTrackingEnabledViews" : true in the metadata. This would allow the UX to block a user from disabling change tracking on a source feature service when its views also have 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.

New at 10.9

A new parameter, returnHasGeometryUpdates, has been added. When set to true, the response includes a hasGeometryUpdates=true property for each layer with updates that have geometry changes.

Request parameters

Parameter

Details

layers

(Required)

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

Syntax

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

Example

layers=0,1,2

layers=[0,1,2] //geodatabase-based features services only support this format
layerQueries

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, its changed features that intersect with the filter geometry are returned.

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 returned. The value of includeRelated is ignored.

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, features from the layer that intersect the geometry are not added.
  • includeRelated—Determines whether to add related rows. The default 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.
  • queryOption—Defines whether or how filters will be applied to a layer. The queryOption was added in 10.2. See Compatibility notes for more information.

Values: none | useFilter | all

Syntax

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

Examples

//Replicate facilities in an area that needs inspection for a service with a facilities layer (0) and an inspection layers (1) that are related
layerQueries={"0":{"queryOption":"useFilter","useGeometry": true,"where":"requires_inspection=yes"}}

//Replicate facilities in an area that needs inspection
layerQueries={"0":{"queryOption":"useFilter","useGeometry":true,"where":"requeires_instpection=yes"},{"1":{"queryOption":"none","includedRelated":true}}

//Replicate all of a specific element in a layer
layerQueries = {"2":{"queryOption": "all"}
geometry

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 Online. In addition to the JSON structures, for envelopes and points, you can specify the geometry with a simpler comma-separated syntax.

Syntax

//JSON structures
geometry={geometry}

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

//Point simple syntax
geometry=<x>,<y>

Example

//JSON structures
geometry={xmin:-104, ymin:35.6, xmax:-94.32, ymax: 41}

//Envelope example
geometry=-104, 35.6, -94.32, 41

//Point example
geometry=-104, 35.6
geomtryType

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

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 the inSR is not specified, the geometry is assumed to be in the special reference of the map.

outSR

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-known 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

The geodatabase version name. This parameter applies only if the hasVersionedData property of the service and the isDataVersioned property of the layer or layers are true. If gdbVersion is not specified, the query will apply to the published map's version.

NoteNote:

This option can only be used with branch-versioned data.

Example

gdbVersion=admin.version1
returnInserts

If true, newly inserted features will be returned. The default is false.

Values: true | false

returnUpdates

If true, updated features will be returned. The default is false.

Values: true | false

returnDeletes

If true, deleted features will be returned. The default is false.

Values: true | false

layerServerGens

(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

If true, the response includes an array of object IDs only. The default is false.

Value: true | false

returnExtentOnly

If true, only the extent of the changes will be returned. The default is false.

Value: true | false

returnHasGeometryUpdates

If true, the response includes a hasGeometryUpdates property set as true for each layer with updates that have geometry changes. The default is false.

If a layer's edits include only inserts, deletes, or updates to fields other than geometry, hasGeometryUpdates is not set or is returned as false. When a layer has multiple rows with updates, only one needs to include a geometry changes for hasGeometryUpdates to be set as true. For an example of this, see the JSON Response examples section below.

Setting returnHasGeometryUpdates to true also requires setting returnUpdates to true. Otherwise, an error is returned.

NoteNote:

returnHasGeometryUpdates is supported when the service's extractChangesCapabilities includes the supportsReturnHasGeometryUpdates property as true.

Values: true | false

returnAttachments

If true, attachment 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

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

The format of the changes returned in the response. The default is json.

Values: sqllite | json

changesExtentGridCell

To optimize localizing changes extent, the value medium is an 8x8 grid that bounds the changes extent. It is used only when returnExtentOnly is true. The default is none.

Values: none | large | medium | small

f

The response format. The default value is html.

Values: html | json

Example usage

Below is a sample workflow that can be used with the extractChanges operation:

  1. Enable the feature service change tracking if it is not enabled by navigating to the updateDefiniton operation:
    https://services.myserver.com/<tenant>/ArcGIS/rest/admin/services/USA/FeatureServer/updateDefinition
    and passing through the following updates (adding ChangeTracking to the list of capabilities):
    "capabilities" :
"Create,Delete,Query,Update,Editing,ChangeTracking,Sync"
  2. Once complete, retrieve the updates service's metadata using the returnUpdates parameter:
    https://services.myserver.com/<tenant>/ArcGIS/rest/services/USA/FeatureServer?f=pjson&returnUpdates=true
  3. Cache the following json object input for layerServerGens in the client side:
    {"layerServerGens":[{"id":0,"minServerGen":1529667,"serverGen":1534028}]}
  4. Once cached, call this operation and pass the layerServerGens parameter and any additional filtering criteria
  5. Update the client cached layerServerGens json object from the extractChanges response.
  6. Continue in steps 2-5.

Example inputs

The following example inputs can be used to return the inserts, updates, and deletions that have been made:

layers=0
returnInserts=true
returnUpdates=true
returnDeletes=true
layerServerGens=[{"id":0,"minServerGen":1529667,"serverGen":1534028}]}
dataFormat=json
f=json

JSON Response examples

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

The following example response has been generated from a request with returnIdsOnly as true, returnInserts as true, returnUpdates as true, and returnDeletes as 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
        ]
      }
    }
  ]
}

The following example response has been generated from a request with returnHasGeometryUpdates as true as well as returnIdsOnly as true, returnInserts as true, returnUpdatesas true, and returnDeletes as true.

{
  "layerServerGens": [
    {
      "id": 0,
      "serverGen": 1526588581400
    },
    {
      "id": 1,
      "serverGen": 1526588581553
    },
    {
      "id": 2,
      "serverGen": 1526588581553
    },
    {
      "id": 3,
      "serverGen": 1526588581553
    }
  ],
  "edits": [
    {
      "id": 0,
      "objectIds": {
        "adds": [],
        "updates": [2026, 2030],
        "deletes": [] 
      },
      "hasGeometryUpdates": true //At least one geometry update was made
    },
    {
      "id": 1,
      "objectIds": {
        "adds": [],
        "updates": [27189, 27190],
        "deletes": []
      },
      "hasGeometryUpdates": false //No geometry updates made
    },
    {
      "id": 3,
      "objectIds": {
        "adds": [12],
        "updates": [],
        "deletes": [17] // No geometry updates were made, no hasGeometryUpdates property returned
      }
    }
  ]
}
Copyright © 1995-2021 Esri. All rights reserved.