Apply Edits (Feature Service/Layer)

Description

This operation adds, updates, and deletes features to the associated feature layer or table in a single call (POST only). The applyEdits operation is performed on a feature service layer resource.

The operation returns the results of the edits. The results are grouped by type of edit (addResults, updateResults, and deleteResults). Each contains an array of edit result objects. Each edit result identifies a single feature and indicates whether the edits were successful or not. If not, it also includes an error code and an error description.

NoteNote:

Hosted feature services support adding or updating BLOB column values in Base64.

NoteNote:

Any geometry edits made to the layer are validated with OGC standards.

Starting at version 10.6, services can be published form enterprise geodatabase layers that have attribute rules. Attribute rules are applied to the back end datasets and fire when edits are applied. Types of attribute rules include calculation rules that automatically apply a calculated value to a field as well as constraint rules that will cause an edit to return an error if the constraint is violated. See the constraint rule violate JSON response examples below.

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

New at 10.9.1

The layer-level applyEdits operation for hosted feature services in ArcGIS Online, and non-hosted feature services in ArcGIS Enterprise, includes an option to process requests asynchronously. This option is ideal for longer running edit operations that may timeout otherwise. The async parameter can be used if the layer resource has the supportsAsyncApplyEdits layer property as true (under advancedEditingCapabilities).

New at 10.9

A new parameter, timeReferenceUnknownClient, has been added at 10.9. Setting timeReferenceUnknownClient as true indicates that the client is capable of working with date field data values that are not in UTC. For more information on this parameter, see the Request parameters table below.

Request parameters

Parameter

Details

adds

The array of features to be added. The structure of each feature in the array is the same as the structure of the json feature object returned by the ArcGIS REST API. Features to be added to a feature layer should include the geometry. Records to be added to a table should not include geometry.

If useGlobalIds is true, the features are added while preserving their globalIds. If useGlobalIds is false or not specified, the globalIds submitted with the features are ignored and the service assigns new globalIds to the new features.

Syntax

adds=[<feature1>, <feature2>]

Example

adds=[
  {
    "geometry" : {"x" : -118.15, "y" : 33.80},  
    "attributes" : {
      "OWNER" : "Joe Smith",
      "VALUE" : 94820.37,
      "APPROVED" : true,
      "LASTUPDATE" : 1227663551096,
      "GlobalID":"{74100804-E229-49b8-8CDC-9B5D3EF03EDA}" 

    }
  },
  {
    "geometry" : { "x" : -118.37, "y" : 34.086 },  
    "attributes" : {
      "OWNER" : "John Doe",
      "VALUE" : 17325.90,
      "APPROVED" : false,
      "LASTUPDATE" : 1227628579430,
       "GlobalID":"{39B856DC-AFE4-4c02-B433-A9361ACD91CF}" 

    }
  }
]
updates

The array of features to be updated. The structure of each feature in the array is the same as the structure of the json feature object returned by the ArcGIS REST API and includes a globalId. Records to be added to a table should not include geometry.

If useGlobalIds is false or not specified, the attributes property of the feature should include the object ID of the feature along with the other attributes (the globalId of the feature is not required):

"attributes" : {
  "OBJECTID" : 37,
  "OWNER" : "Joe Smith",
  "VALUE" : 94820.37,
  "APPROVED" : true,
  "LASTUPDATE" : 1227667627940
}

If useGlobalIds is true, the globalId is used to identify the feature when applying the update (the object ID of the feature is not required.)

"attributes": {
	 "OWNER": "Joe Smith",
	 "VALUE": 94820.37,
	 "APPROVED": true,
	 "LASTUPDATE": 1227667627940,
	 "GlobalID": "{9537AFCE-BF6B-4931-93E8-403E12D76916}"
}

Syntax

updates=[<feature1>, <feature2>]

Example 1:

[
  {
    "geometry" : {"x" : -118.15, "y" : 33.80},  
    "attributes" : {
      "OBJECTID" : 37,
      "OWNER" : "Joe Smith",
      "VALUE" : 94820.37,
      "APPROVED" : true,
      "LASTUPDATE" : 1227667627940
    }
  },
  {
    "geometry" : { "x" : -118.37, "y" : 34.086 },  
    "attributes" : {
      "OBJECTID" : 462,
      "OWNER" : "John Doe",
      "VALUE" : 17325.90,
      "APPROVED" : false,
      "LASTUPDATE" : 9269154204840
    }
  }
]

Example 2: (useGlobalIds is true)

[
  {
    "geometry": {
      "x": -118.15,
      "y": 33.8
    },
    "attributes": {
      "OWNER": "Joe Smith",
      "VALUE": 94820.37,
      "APPROVED": true,
      "LASTUPDATE": 1227667627940,
      "GlobalID": "{1A9F8368-F9BB-428B-BB03-F45724362DB5}"
    }
  },
  {
    "geometry": {
      "x": -118.37,
      "y": 34.086
    },
    "attributes": {
      "OWNER": "John Doe",
      "VALUE": 17325.9,
      "APPROVED": false,
      "LASTUPDATE": 9269154204840,
      "GlobalID": "{6CE34136-EC3A-40D7-80BF-E1D9BE33812A }"
    }
  }
]

deletes

The object IDs of the features/records to be deleted. If useGlobalIds is false or not specified, the objectIds of the features to be deleted must be provided. If useGlobalIds is true, the globalIds of the features to be deleted must be provided.

Syntax

deletes=<objectId1>, <objectId2>

Example

deletes=37, 462
deletes=[37, 462]
deletes=["{1A9F8368-F9BB-428B-BB03-F45724362DB5}","{6CE34136-EC3A-40D7-80BF-E1D9BE33812A}"]
gdbVersion

//This option was added at 10.1

The geodatabase version to apply the edits. This parameter applies only if the isDataVersioned property of the layer is true.

If the gdbVersion parameter is not specified, edits are made to the published map’s version.

Syntax: gdbVersion=<version>

Example: gdbVersion=SDE.DEFAULT

returnEditMoment

(Optional)

Introduced at 10.5, only applicable with ArcGIS Server services only. Specifies whether the response will report the time edits were applied. If set to true, the server will return the time in the response's editMoment key. The default value is false.

Values: true | false

rollbackOnFailure

(Optional)

//This option was added at 10.1

Specifies whether the edits should be applied only if all submitted edits succeed. If false, the server will apply the edits that succeed even if some of the submitted edits fail. If true, the server will apply the edits only if all edits succeed. The default value is true.

Not all data supports setting this parameter. Query the supportsRollbackonFailureParameter property of the layer to determine whether a layer supports setting this parameter. If supportsRollbackOnFailureParameter = false for a layer, then when editing this layer, rollbackOnFailure will always be true, regardless of how the parameter is set. However, if supportsRollbackonFailureParameter = true, the rollbackOnFailure parameter value will be honored on edit operations.

Values: true|false

Example: rollbackOnFailure=true

useGlobalIds

(Optional)

Introduced at 10.4. When set to true, the features and attachments in the adds, updates, deletes, and attachments parameters are identified by their gloablIds rather than their objectId or attachmentId. The service adds the new features and attachments while preserving the globalId submitted in the payload. If the globalId of a feature or attachment collides with a pre-existing feature or attachment, the addition of that feature or attachment fails. Other additions, updates, or deletions are attempted if rollbackOnFailure is false. If rollbackOnFailure is true, the whole operation fails and rolls back on any failure, including a globalId collision. The default value is false.

NoteNote:

This parameter requires the layer's supportsApplyEditsWithGlobalIds property to be true.

Values: true | false

attachments

(Optional)

Introduced at 10.4 This parameter adds, updates, or deletes attachments. It applies only when the useGlobalIds parameter is set to true. For adds, the globalIds of the attachments provided by the client are preserved. When useGlobalIds is true, updates and deletes are identified by each feature or attachment globalId, rather than their objectId or attachmentId. This parameter requires the layer's supportsApplyEditsWithGlobalIds property to be true.

Attachments to be added or updated can use either pre-uploaded data or base 64 encoded data.

NoteNote:
Attachments can be edited using the feature resource regardless of the supportsApplyEditsWithGlobalIds property.

Syntax:

{
  "adds": [<attachment1>, <attachment2>],
  "updates": [<attachment1>, <attachment2>],
  "deletes": ["<attachmentGlobalId1>", "<attachmentGlobalId2>"]
}

Example:

{
  "adds": [
    {
      "globalId": "{55E85F98-FBDD-4129-9F0B-848DD40BD911}",
      "parentGlobalId": "{02041AEF-4174-4d81-8A98-D7AC5B9F4C2F}",
      "contentType": "image/pjpeg",
      "name": "Pothole.jpg",
      "uploadId": "{DD1D0A30-CD6E-4ad7-A516-C2468FD95E5E}"
    },
    {
      "globalId": "{3373EE9A-4619-41B7-918B-DB54575465BB}",
      "parentGlobalId": "{6FA4AA68-76D8-4856-971D-B91468FCF7B7}",
      "contentType": "image/pjpeg",
      "name": "Debree.jpg",
      "data": "<base 64 encoded data>"
    }
  ],
  "updates": [
    {
      "globalId": "{8FDD9AEF-E05E-440A-9426-1D7F301E1EBA}",
      "contentType": "image/pjpeg",
      "name": "IllegalParking.jpg",
      "uploadId": "{57860BE4-3B85-44DD-A0E7-BE252AC79061}"
    }
  ],
  "deletes": [
    "{95059311-741C-4596-88EF-C437C50F7C00}",
    "{18F43B1C-2754-4D05-BCB0-C4643C331C29}"
  ]
}

trueCurveClient

(Optional)

Introduced at 10.5. Indicates to the server whether the client is true curve capable. When set to true, this indicates to the server that true curve geometries should be downloaded and that geometries containing true curves should be consumed by the map service without densifying it. When set to false, this indicates to the server that the client is not true curves capable. The default value is false.

Values: true | false

sessionID

(Optional)

Introduced at 10.6. The sessionID is a GUID value that clients establish at the beginning and use throughout the edit session. The sessonID ensures isolation during the edit session. The sessionID parameter is set by a client during long transaction editing on a branch version.

Syntax

sessionID=<sessionID>

Example

sessionID={E81C2E2D-C6A7-40CB-BF61-FB499E53DD1D}
usePreviousEditMoment

(Optional)

Introduced at 10.6. The usePreviousEditMoment parameter is used to apply the edits with the same edit moment as the previous set of edits. This allows an editor to apply single block of edits partially, complete another task and then complete the block of edits. This parameter is set by a client during long transaction editing on a branch version.

When set to true, the edits are applied with the same edit moment as the previous set of edits. When set to false or not set (default) the edits are applied with a new edit moment.

Values: true | false

datumTransformation

(Optional)

Introduced at 10.8. This parameter applies a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference. When specifying transformations, you need to think about which datum transformation best projects the layer (not the feature service) to the outSR and sourceSpatialReference property in the layer resource report. For a list of valid datum transformation ID values ad well-known text strings, see Coordinate systems and transformations (values applicable for ArcGIS Desktop, ArcGIS Enterprise, ArcGIS Pro, and ArcGIS Runtime). For more information on datum transformations, please see the transformation parameter in the Project operation.

Syntax

//Syntax to apply a simple transformation
datumTransformation=<wkid>

//Syntax to apply a simple transformation
datumTransformation={"wkt": "<WKT>"}

//Syntax to apply a composite transformation
datumTransformation={"geoTransforms":[{"wkid":<id>,"forward":<true|false>},{"wkt":"<WKT>","forward":<true|false>}]}

Example

//Applies a simple transformation
datumTransformation=1623

//Applies a composite transformation
datumTransformation={
  "geoTransforms":[
    {
      "wkid":1088,
      "transformForward": true
    },
    {
      "wkit": "GEOGTRAN[\"S_JTSK_To_WGS_1984_1\",GEOGCS[\"GCS_S_JTSK\",DATUM[\"D_S_JTSK\",SPHEROID[\"Bessel_1841\",6377397.155,299.1528128]],
        PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_
        1984\",6378137.0,298.257223563]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],METHOD[\"Position_Vector\"],
        PARAMETER[\"X_Axis_Translation\",570.8],PARAMETER[\"Y_Axis_Translation\",85.7],PARAMETER[\"Z_Axis_Translation\",462.8],
        PARAMETER[\"X_Axis_Rotation\",4.998],PARAMETER[\"Y_Axis_Rotation\",1.587],PARAMETER[\"Z_Axis_Rotation\",5.261],
        PARAMETER[\"Scale_Difference\",3.56]]",
      "transformForward":false
    }
  ]
}
timeReferenceUnknownClient

Setting timeReferenceUnknownClient as true indicates that the client is capable of working with data values that are not in UTC. If its not set to true, and the service layer's datesInUnknownTimeZone property is true, then an error is returned. The default is false

Its possible to define a service's time zone of date fields as unknown. Setting the time zone as unknown means that date values will be returned as-is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the datesInUnknownTimeZone layer property as true. Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields which are stored and returned in UTC even when the time zone is set to unknown.

Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service in order to avoid problems.. Setting this parameter to true indicates that the client is capable of working with unknown date values that are not in UTC.

NoteNote:

ArcGIS Pro 2.7 or newer can work with these feature services.

Value: true | false

async

New at 10.9.1. The async parameter can be used if the layer resource has the supportsAsyncApplyEdits property as true (found under advancedEditingCapabilities). 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 (statusUrl). The default value is false. For more information, see the topic on asynchronous usage for more information.

The status and resultUrl properties are returned when checking the status of a job. However, the other asynchronous properties may not be returned. Once the status is COMPLETED, a resultUrl is provided that returns responses matching the JSON response example below.

Async applyEdits is meant to be used for longer running edit operations that may timeout in synchronous mode while the client is waiting for a response. For much larger and longer running processes, it is recommended that other operations, such as append, are used instead of applyEdits. For ArcGIS Enterprise non-hosted feature services, the async process is subject to the feature service timeout settings. For example, if the maximum time a client can use a service is 10 minutes, the async process will run up to 10 minutes. The number of instances configured per machine will also be shared by both synchronous and asynchronous calls.

Values: true | false

f

The response format. The default response format is html.

Values: html | json

Example usage

https://machine.domain.com/webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/0/applyEdits?

Example one

Add an array of features using the applyEdits operation on a feature service layer resource.

Sample input for adds, represented by an array of features:

adds=[
  {
    "attributes": {
      "req_id": "508389",
      "req_type": "Graffiti Complaint - Public Property",
      "req_date": "09\/19\/2009",
      "req_time": "18:44",
      "address": "11TH ST and HARRISON ST",
      "x_coord": "6008925.0",
      "y_coord": "2108713.8",
      "district": "6",
      "status": 1
    },
    "geometry": {
      "x": -122.41247978999991,
      "y": 37.770630098000083
    }
  },
	 {
    "attributes": {
      "req_id": "508395",
      "req_type": "Graffiti Complaint - Public Property",
      "req_date": "09\/19\/2009",
      "req_time": "19:01",
      "address": "13TH ST and MANCHESTER ST",
      "x_coord": "6008929.0",
      "y_coord": "2108713.9",
      "district": "6",
      "status": 1
    },
    "geometry": {
      "x": -121.42248867898987,
      "y": 38.790630098000452
    }
  }
]

Example two

Update an array of features using the applyEdits operation on a feature service layer resource.

Sample input for updates, represented by an array of features:

updates=[
  {
    "attributes": {
	     "objectid: 1234567
      "req_id": "508389",
      "req_type": "Graffiti Complaint - Private Property",
      "req_date": "09\/19\/2009",
      "req_time": "18:44",
      "address": "11TH ST and HARRISON ST",
      "x_coord": "6008925.0",
      "y_coord": "2108713.8",
      "district": "6",
      "status": 2
    },
    "geometry": {
      "x": -122.41247978999991,
      "y": 37.770630098000083
    }
  },
	 {
    "attributes": {
      "req_id": "508395",
      "req_type": "Graffiti Complaint - Public Property",
      "req_date": "09\/19\/2009",
      "req_time": "19:01",
      "address": "13TH ST and MANCHESTER ST",
      "x_coord": "6008929.0",
      "y_coord": "2108713.9",
      "district": "6",
      "status": 2
    },
    "geometry": {
      "x": -121.42248867898987,
      "y": 38.790630098000452
    }
  }
]

Example three

Delete features using the applyEdits operation on a feature service layer resource.

The input for deletes is a list of objectIds of the features to be deleted.

deletes=37, 462

JSON Response syntax

{
  "addResults": [<editResult1>}, <editResult2>],
  "updateResults": [<editResult1>}, <editResult2>],
  "deleteResults": [<editResult1>}, <editResult2>],
  "attachments": {
    "addResults": [<attachmentEditResult1>, <attachmentEditResult2>],
    "updateResults": [<attachmentEditResult1>, <attachmentEditResult2>],
    "deleteResults": [<attachmentEditResult1>, <attachmentEditResult2>]
  }
}

JSON Response examples

Example one

General successful response for a included adds, updates, and deletes in the request:

{
  "addResults": [
    {
      "objectId": 618,
      "success": true
    },
    {
      "success": false,
      "error": {
        "code": -2147217395,
        "description": "Setting of Value for depth failed."
      }
    }
  ],
  "updateResults": [
    {
      "objectId": 50,
      "success": true
    }
  ],
  "deleteResults": [
    {
      "objectId": 25,
      "success": true
    },
    {
      "objectId": 26,
      "success": true
    }
  ]
}

Example two

Where useGlobalids is true and the attachments parameter is set:

{
  "addResults": [
    {
      "objectId": 618,
      "globalId": "{74100804-E229-49b8-8CDC-9B5D3EF03EDA}",
      "success": true
    },
    {
      "objectId": 619,
      "globalId": "{39B856DC-AFE4-4c02-B433-A9361ACD91CF}",
      "success": true
    }
  ],
  "updateResults": [
    {
      "objectId": 50,
      "globalId": "{9537AFCE-BF6B-4931-93E8-403E12D76916}",
      "success": true
    }
  ],
  "deleteResults": [
    {
      "objectId": 25,
      "globalId": "{1A9F8368-F9BB-428B-BB03-F45724362DB5}",
      "success": true
    },
    {
      "objectId": 26,
      "globalId": "{6CE34136-EC3A-40D7-80BF-E1D9BE33812A}",
      "success": true
    }
  ],
  "attachments": {
    "addResults": [
      {
        "objectId": 500,
        "globalId": "{55E85F98-FBDD-4129-9F0B-848DD40BD911}",
        "success": true
      },
      {
        "objectId": 501,
        "globalId": "{3373EE9A-4619-41B7-918B-DB54575465BB}",
        "success": true
      }
    ],
    "updateResults": [
      {
        "objectId": 600,
        "globalId": "{8FDD9AEF-E05E-440A-9426-1D7F301E1EBA}",
        "success": true
      }
    ],
    "deleteResults": [
      {
        "objectId": 800,
        "globalId": "{95059311-741C-4596-88EF-C437C50F7C00}",
        "success": true
      },
      {
        "objectId": 801,
        "globalId": " {18F43B1C-2754-4D05-BCB0-C4643C331C29}",
        "success": true
      }
    ]
  }
}

Example three

Where a constraint rule is violated and rollBackOnFailure is true:

{
  "error": {
    "code": 400,
    "extendedCode": -2147207418,
    "message": "Unable to complete operation.",
    "details": [
      "Violated attribute constraint rule. [Error No: -1, ]",
      "Operation rolled back."
    ]
  }
}

Example four

Where a constraint rule is violated and rollBackOnFailure is false:

{
  "addResults": [],
  "updateResults": [
    {
      "objectId": 2,
      "globalId": "{B703ACAC-A1A8-4F49-BB19-1E684A67A265}",
      "success": false,
      "error": {
        "code": 1019,
        "extendedCode": -2147207418,
        "description": "Violated attribute constraint rule. [Error No: -1, ]"
      }
    },
    {
      "objectId": 1,
      "globalId": "{2FACC38A-3E3E-43A5-A6EB-BC9075407EC8}",
      "success": true
    }
  ],
  "deleteResults": []
}

Example five

Where async is true. A status URL is returned, demonstrated below:

{
  "statusUrl": "https://machine.domain.com/webadaptor/rest/services/testservice/FeatureServer/jobs/sf_j9563cb9e-8cf4-4c99-945d-09e43d408ac7/status"
}

Making a request to job status URL will return the following response once the operation has completed:

{
  "status": "COMPLETED",
  "resultUrl": " https://machine.domain.com/webadaptor/rest/directories/arcgisoutput/testservice _MapServer/j9563cb9e-8cf4-4c99-945d-09e43d408ac7.json"
}

The resultUrl returned in the example above gives access to the results of applyEdits:

{
  "addResults": [
    {
      "objectId": 53,
      "globalId": "{2AF16CAD-D5B8-4F4C-BF36-432FBF660C0B}",
      "success": true
    }
  ],
  "updateResults": [ ],
  "deleteResults": [ ]
}

Example six

This example shows an error case where an edit is attempted for a capability that is not supported and async is true. As with example five, a statusUrl is returned in the response:

{
  "statusUrl": "https://machine.domain.com/webadaptor/rest/services/VRNVA/FeatureServer/jobs/sf_j7aadb493-7987-44cb-9a4c-53e1f9fd97bf/status"
}

Making a request to job status URL will return the following response once the operation has completed:

{
  "status": "COMPLETED",
  "resultUrl": "https://machine.domain.com/webadaptor/rest/directories/arcgisoutput/VRNVA_MapServer/j7aadb493-7987-44cb-9a4c-53e1f9fd97bf.json"
}

In this case, however, info returned from the resultUrl contains the error:

{
  "error" : {
    "code" : 400,
    "message" : "Requested operation is not supported by this service.",
    "details" : []
  }
}