Task operation: execute (REST)

In this topic

How to execute the task

Each geoprocessing task has a supported operation based the Execution type property of the parent service. If the Execution type of the geoprocessing service is synchronous, all geoprocessing tasks within the service will support the Execute Task operation only. The URL for execute task operation is http://<gp-task-url>/execute.

How to execute the task

To execute a geoprocessing task, the client must construct a request URL with the Execute task URL and append name-value pairs of all the required input parameters of the task as shown below:

http://<task-url>/execute?parameter1=value1&parameter2=value2

parameter1=value1 is a name-value pair where parameter1 is the name of the task parameter and value1 is the ASCII representation of the JSON value. When the request URL is sent to the server, the task runs on the server with the given input values. At the end of execution, if the task succeeds the server will construct a response with the values of the output parameters and will send it to the client as illustrated below. If the task fails, the server will send an error response to the client.

Execute task at the server

Successful task result

The response sent by the client is called a geoprocessing task result and includes the output parameter values and messages generated by the geoprocessing task during execution. The task result will have an array of output parameters. Each output parameter in the array will have a paramName, dataType, and its value. The task result will also have an array of geoprocessing messages. Each element in the message array will have a type (esriJobMessageTypeInformative, esriJobMessageTypeWarning, or esriJobMessageTypeError) and a message description. The messages returned by the server depends on the message level of the geoprocessing service. If the message level is set to None, the server will not return any messages.

Learn more about message levels in geoprocessing services

The task result JSON for a Buffer Points task with one output parameter, Output_Polygons, is shown below.

JSON representation of geoprocessing task result. (The geometry and message array values have been truncated in the example for brevity.)

{
 "results":[
  {"paramName": "Output_Polygons",
   "dataType": "GPFeatureRecordSetLayer",
   "value":{
    "displayFieldName": "",
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 102726,"latestWkid": 102726},
    "fields":[{"name": "FID","type": "esriFieldTypeOID","alias": "FID"},
              {"name": "BUFF_DIST","type": "esriFieldTypeDouble","alias": "BUFF_DIST"},
              {"name": "Shape_Length","type": "esriFieldTypeDouble","alias": "Shape_Length"},
              {"name": "Shape_Area","type": "esriFieldTypeDouble","alias": "Shape_Area"},
    "features": [{"attributes": {"FID": 1,"BUFF_DIST": 3280.83333333,"Shape_Length": 20613.401930152133,
    "Shape_Area": 3.381121258723078E7},
    "geometry": {"rings": [[[7643591.49993746,684676.8331969529],[7643683.927544728,684675.5310036689],...more]]},        
    "exceededTransferLimit": false
           }
   }],
 "messages": [{"type":"esriJobMessageTypeInformative","description": "Start Time: Mon Feb 27 15:56:09 2012"},
              {"type":"esriJobMessageTypeInformative","description": "Executing (BufferPoints): BufferPoints.. "}...more
  ]
}

Error response

An execute task operation may fail because of invalid parameters or other geoprocessing tool failures. In such cases, the server will return a geoprocessing task error with a code number, the string Unable to complete operation., and details of the failure. The JSON format for the error is given below:

Error JSON returned by a geoprocessing task

{"error":{"code":400,"message":"Unable to complete operation.","details":[]}}

The level of detail in the error response depends on the message level of the geoprocessing service. Based on the message level, the details property will include appropriate geoprocessing tool messages generated during execution. If the input parameters of the tool are invalid or if the message level property of the geoprocessing service is set to None, the details property of the error response will be empty as shown in above example.

Note: