- URL:
- https://<root>/<serviceName>/FeatureServer/extractChanges
- Methods:
POST
Description
The extract
operation can be used to retrieve changes made to a service with the Change
capability enabled. 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 Change
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 Change
capability, the extract
operation can be used to get changes.
Check the subproperties of extract
on the service resource to see which extract
options are supported. These include the following:
supports
—Allows the use of theReturn Ids Only return
parameter, which returns only the IDs of the features that were changed.Ids Only supports
—Allows the use of theReturn Extent Only return
parameter to return the extent of the changed features.Extent Only supports
—Allows the use of theReturn Attachments return
parameter. This will return any attachments associated with the changed features.Attachments supports
—Allows the use ofLayer Queries layer
to limit the changed features returned using filters such as a where clause.Queries supports
—Allows the use of theGeometry geometry
parameter, which will return changed features within a defined geometry.supports
—Allows full rows to be returned for updates or inserts as opposed to IDs only.Return Feature supports
—Introduced at ArcGIS Enterprise 11.0. Allows the use of theFields To Compare fields
parameter to further group feature updates based on which fields were changed.To Compare supports
-Introduced at ArcGIS Enterprise 11.0. Allows the use of theServer Gens server
parameter to provide a range of server generations for all layers. This can be used instead ofGens layer
, which setsServer Gens server
for each layer individually.Gens
Enterprise geodatabase-based feature services published from ArcGIS Pro 2.2, supports
is the only subproperty set to true. This allows you to use the extract
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 Change
capability to or from the feature service.
{"capabilities": "Create,Delete,Query,Update,Editing,ChangeTracking"}
A feature service with change tracking enabled returns additional metadata, demonstrated in the example below. The layer
property in change
must be cached on the client. The client needs to pass change layer
to the server when requesting the latest changes from the server.
"changeTrackingInfo": {"lastSyncDate": 1519247516232,"layerServerGens": [{"id": 0,"minServerGen": 1529667,"serverGen": 1534028}]},
Hosted feature service views
The Change
service capability can be enabled or disabled on a feature service view if its source feature service has Change
enabled. Change
capability cannot be disabled on a source feature service if any of its views have Change
enabled.
has Change Tracking Enabled Views
service property
Source feature services with views or map/tile service with change tracking enabled will return has
as 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 11.2
Hosted feature services on a relational datastore now supports the return
parameter, which allows you to specify whether the full information for a deleted feature is returned, or just the feature's identifier.
New at 11.1
Starting at ArcGIS Enterprise 11.1, this operation includes support for the return
parameter. This parameter allows you to specify whether the full information for a deleted feature is returned, or just the feature's identifier. This is supported for ArcGIS Enterprise non-hosted feature services and ArcGIS Online hosted feature services.
New at 11.0
-
The
extract
operation has been expanded to support the following changes, support for which depend on properties underChanges extract
on the service-level resource:Changes Capabilities - A new parameter,
fields
. Support for this is indicated when theTo Compare supports
property, underFields To Compare extract
, is set asChanges Capabilities true
. - The ability to return features rather than IDs only. Support for this is indicated when the
supports
property, underFeature Return extract
, is set asChanges Capabilities true
. - A new parameter,
server
. Support for this is indicated when theGens supports
property, underServer Gens extract
, is set asChanges Capabilities true
. - The ability to return attachment differences. Support for this is indicated when the
supports
property, underReturn Attachments extract
, is set asChanges Capabilities true
.
- A new parameter,
-
The
Change
capability can now be enabled on a feature service resource using theTracking update
operation. AddingDefinition Change
exposes theTracking extract
operation and adds theChanges extract
property to the feature service resource. This property describes theChanges Capabilities extract
operation that are supported for that feature service.Changes
New at 10.9
A new parameter, return
, has been added. When set to true
, the response includes a has
property for each layer with updates that have geometry changes.
Request parameters
Parameter | Details |
---|---|
(Required) | The list of layers and tables to include in the replica. Syntax
Example
|
(Required) | Introduced at 11.0. This parameter sets the Support for this parameter is indicated when the service-level Syntax
Example
|
| In addition to the layers and geometry parameters, the When the value is The properties include the following:
Values: Syntax
Examples
|
| 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
Example
|
| The type of geometry specified by the Values: |
| The spatial reference of the input |
| 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 ( |
| If Values: |
| If Values: |
| If Values: |
(Required) | The
Syntax
Example
|
| If Value: |
| If Value: |
| If If a layer's edits include only inserts, deletes, or updates to fields other than geometry, Setting Values: |
| If Values: |
| If Value: |
| The format of the changes returned in the response. The default is Values: |
| To optimize localizing changes extent, the value Values: |
| Introduced at 11.0. This parameter allows you to determine if any array of fields has been updated. The accepted values for this parameter is a fields array that include the fields you want to evaluate. The response includes a Support for this parameter is indicated when the service-level Syntax
Example
|
| Introduced at ArcGIS Enterprise 11.1 for ArcGIS Enterprise non-hosted feature services. Supported for ArcGIS Online hosted feature services. Specifies whether the full information for a deleted feature is returned ( Values: |
| The response format. The default value is Values: |
Example workflow
Below is a sample workflow that can be used with the extract
operation:
-
Enable the feature service change tracking if it is not enabled by navigating to the
update
operation:Definiton Use dark colors for code blocks Copy https://services.myserver.com/<tenant>/ArcGIS/rest/admin/services/USA/FeatureServer/updateDefinition
and passing through the following updates (adding
Change
to the list of capabilities):Tracking Use dark colors for code blocks Copy "capabilities" : "Create,Delete,Query,Update,Editing,ChangeTracking,Sync"
-
Once complete, retrieve the updates service's metadata using the
return
parameter:Updates Use dark colors for code blocks Copy https://services.myserver.com/<tenant>/ArcGIS/rest/services/USA/FeatureServer/extractChanges?returnUpdates=true&f=pjson
-
Cache the following json object input for
layer
in the client side:Server Gens Use dark colors for code blocks Copy {"layerServerGens":[{"id":0,"minServerGen":1529667,"serverGen":1534028}]}
-
Once cached, call this operation and pass the
layer
parameter and any additional filtering criteriaServer Gens -
Update the client cached
layer
json object from theServer Gens extract
response.Changes -
Continue in steps 2-5.
Example usage
Example one
The following is a sample POST request for the extract
operation that can be used to return the inserts, updates, and deletions that have been made to a specific service:
POST /webadaptor/Hosted/myFeatureService/FeatureServer/extractChanges HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
layers=0&serverGens=&layerQueries=&geometry=&geometryType=esriGeometryEnvelope&inSR=&outSR=&returnInserts=true&returnUpdates=true&returnDeletes=true&layerServerGens=[{"id":0,"minServerGen":1529667,"serverGen":1534028}]}&returnIdsOnly=false&returnHasGeometryUpdates=false&returnExtentOnly=false&returnAttachments=true&returnAttachmentsDataByUrl=true&transportType=esriTransportTypeUrl&dataFormat=json&fieldsToCompare=&f=pjson
The example below reflects the specific inputs for this request:
layers=0
returnInserts=true
returnUpdates=true
returnDeletes=true
layerServerGens=[{"id":0,"minServerGen":1529667,"serverGen":1534028}]}
dataFormat=json
f=json
Example two
The following is a sample POST request for the extract
operation that can be used to return the inserts, updates, and deletions that have been made to a specific service, including any updates made to a specific field:
POST /webadaptor/Hosted/myFeatureService/FeatureServer/extractChanges HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
layers=0&serverGens=&layerQueries=&geometry=&geometryType=esriGeometryEnvelope&inSR=&outSR=&returnInserts=true&returnUpdates=true&returnDeletes=true&layerServerGens=[{"id": 0,"serverGen": 1653608093000}]&returnIdsOnly=true&returnHasGeometryUpdates=false&returnExtentOnly=false&returnAttachments=true&returnAttachmentsDataByUrl=true&transportType=esriTransportTypeUrl&dataFormat=json&fieldsToCompare={"fields": ["type"]}&f=pjson
The example below reflects the specific inputs for this request:
layers: [0]
layerServerGens: [{"id": 0,"serverGen": 1653608093000}]
fieldsToCompare: {"fields": ["type"]}
returnIdsOnly=true
returnInserts=true
returnUpdates=true
returnDeletes=true
The sample request returns the following JSON response:
{
"layerServerGens": [
{
"id": 0,
"serverGen": 1653614103746
}
],
"edits": [
{
"id": 0,
"objectIds": {
"adds": [73143],
"updates": [65715],
"deletes": []
},
"fieldUpdates": [65715]
}
]
}
Example three
The following is a sample POST request for the extractChanges operation that can be used to receive an asynchronous response
POST /webadaptor/Hosted/myFeatureService/FeatureServer/extractChanges HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
layers=0&serverGens=&layerQueries=&geometry=&geometryType=esriGeometryEnvelope&inSR=&outSR=&returnInserts=true&returnUpdates=true&returnDeletes=true&layerServerGens=[{"id": 0,"serverGen": 1653608093000}]&returnIdsOnly=false&returnHasGeometryUpdates=false&returnExtentOnly=false&returnAttachments=true&returnAttachmentsDataByUrl=true&transportType=esriTransportTypeUrl&dataFormat=json&fieldsToCompare=&f=pjson
The example below reflects the specific inputs for this request:
layers: [0]
layerServerGens: [{"id": 0,"serverGen": 1653608093000}]
returnIdsOnly=false
returnInserts=true
returnUpdates=true
returnDeletes=true
The request above returns an asynchronous response:
{
"statusUrl": "https://machine.domain.com/webadaptor/rest/services/testfs/FeatureServer/jobs/j05e8901c85d341a1b7eeb6b52d470b46"
}
You can check the status of your request by polling the status
address provided in the response above. The response below is returned when the status
is Completed
:
{
"responseType": "esriDataChangesResponseTypeEdits",
"resultUrl": "https://machine.domain.com/webadaptor/rest/directories/arcgisoutput/VRNVA_MapServer/_ags_fsf5ce58038ec84c3c948842e05fb80e20.json",
"submissionTime": 1653614927000,
"lastUpdatedTime": 1653614930000,
"status": "Completed"
}
The contents of the json file from the result
contains the following information for this request:
{
"layerServerGens": [
{
"id": 0,
"serverGen": 1653614103746
}
],
"edits": [
{
"id": 0,
"objectIds": {
"adds": [73143],
"updates": [65715],
"deletes": []
},
"fieldUpdates": []
}
]
}
JSON Response examples
Example one
{
"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"
]
}
}
]
}
Example two: return IDs, insertions, updates, and deletions
The following example response has been generated from a request with return
as true
, return
as true
, return
as true
, and return
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
]
}
}
]
}
Example three: return IDs, insertions, updates, deletions, and geometry updates
The following example response has been generated from a request with return
as true
as well as return
as true
, return
as true
, return
as true
, and return
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
}
}
]
}
Example four: return full information for deleted feature
The sample response below is returned when a request specifies return
as true
, return
as false
, and return
as true
, allowing for the full information for a deleted feature to be listed:
{
"edits": [
{
"id": 0,
"features": {
"adds": [],
"updates": [],
"deletes": [
{
"geometry": {
"x": -141.97926397204083,
"y": 45.16245817367502
},
"attributes": {
"objectid": null,
"state": "CA",
"number": null,
"name": null,
"elevation": null,
"type": null,
"status": null,
"time_code": null,
"known_erup": null,
"max_vei": 3,
"globalid": "{F8A78D45-AECF-4BC7-A4E6-037B51F4CC77}",
"dt": null,
"xssfield": null,
"created_user": "admin",
"created_date": 1651509803000,
"last_edited_user": "admin",
"last_edited_date": 1670626687000,
"objectid_1": 72236
}
}
]
},
"attachments": {
"adds": [],
"updates": [],
"deletes": []
}
}
],
"layerServerGens": [
{
"id": 0,
"serverGen": 1675232887090
}
],
"transportType": "esriTransportTypeUrl"
}
Example five: return ID of deleted feature
The following response is returned when the request sets return
as false
, which returns just the ID of the deleted feature:
{
"edits": [
{
"id": 0,
"features": {
"adds": [],
"updates": [],
"deleteIds": ["{F8A78D45-AECF-4BC7-A4E6-037B51F4CC77}"]
},
"attachments": {
"adds": [],
"updates": [],
"deleteIds": []
}
}
],
"layerServerGens": [
{
"id": 0,
"serverGen": 1675232949666
}
],
"transportType": "esriTransportTypeUrl"
}