Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Geoprocessor

require(["esri/tasks/Geoprocessor"], function(Geoprocessor) { /* code goes here */ });

Description

(Added at v1.0)
Represents a GP Task resource exposed by the ArcGIS Server REST API. A GP Task resource represents a single task in a GP service published using the ArcGIS Server and it supports one of the following operations:
  • "execute" - performed on a GP Task resource when the execution type is synchronous.
  • "submitJob" - performed on an asynchronous GP Task resource.

Samples

Search for samples that use this class.

Constructors

NameSummary
new Geoprocessor(url)Creates a new Geoprocessor object that represents the GP Task identifed by a URL.

Properties

NameTypeSummary
outSpatialReferenceSpatialReferenceThe spatial reference of the output geometries.
outputSpatialReferenceSpatialReferenceDeprecated at v2.0, use outSpatialReference instead..
processSpatialReferenceSpatialReferenceThe spatial reference that the model will use to perform geometry operations.
updateDelayNumberThe time interval in milliseconds between each job status request sent to an asynchronous GP task.
urlStringArcGIS Server Rest API endpoint to the resource that receives the geoprocessing request.

Methods

NameReturn typeSummary
cancelJob(jobId, callback, errback)DeferredCancel an asynchronous geoprocessing job.
cancelJobStatusUpdates(jobId)NoneCancels the periodic job status updates initiated automatically when submitJob() is invoked for the job identified by jobId.
checkJobStatus(jobId, callback?, errback?)DeferredSends a request to the GP Task for the current state of the job identified by jobId.
execute(inputParameters, callback?, errback?)DeferredSends a request to the server to execute a synchronous GP task.
getResultData(jobId, parameterName, callback?, errback?)DeferredSends a request to the GP Task to get the task result identified by jobId and resultParameterName.
getResultImage(jobId, parameterName, imageParameters, callback?, errback?)DeferredSends a request to the GP Task to get the task result identified by jobId and resultParameterName as an image.
getResultImageLayer(jobId, parameterName?, imageParameters?, callback?)ArcGISDynamicMapServiceLayerGet the task result identified by jobId and resultParameterName as an ArcGISDynamicMapServiceLayer.
setOutSpatialReference(spatialReference)NoneSets the well-known ID of the spatial reference of the output geometries.
setOutputSpatialReference(spatialReference)NoneDeprecated at v2.0, use setOutSpatialReference instead..
setProcessSpatialReference(spatialReference)NoneSets the well-known ID of the spatial reference that the model uses to perform geometry operations.
setUpdateDelay(delay)NoneSets the time interval in milliseconds between each job status request sent to an asynchronous GP task.
submitJob(inputParameters, callback?, statusCallback?, errback?)DeferredSubmits a job to the server for asynchronous processing by the GP task.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
error
{
  error: <Error>
}
Fires when an error occurs when executing the task.
execute-complete
{
  messages: <GPMessage[]>,
  results: <ParameterValue[]>
}
Fires when a synchronous GP task is completed.
get-result-data-complete
{
  result: <ParameterValue>
}
Fires when the result of an asynchronous GP task execution is available.
get-result-image-complete
{
  mapImage: <MapImage>
}
Fires when a map image is generated by invoking the getResultImage method.
get-result-image-layer-completeFires when getResultImageLayer method has completed.
job-cancelFires when the geoprocessing job is cancelled using the cancelJob method.
job-completeFires when an asynchronous GP task using submitJob is complete.
status-updateFires when a job status update is available.
Constructor Details

new Geoprocessor(url)

Creates a new Geoprocessor object that represents the GP Task identifed by a URL.
Parameters:
<String> url Required URL to the ArcGIS Server REST resource that represents a geoprocessing service. An example is http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Network. For more information on constructing a URL, see The Services Directory and the REST API.
Sample:
require([
  "esri/tasks/Geoprocessor", ... 
], function(Geoprocessor, ... ) {
  var gp = new Geoprocessor("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_Currents_World/GPServer/MessageInABottle");
  ...
});
Property Details

<SpatialReference> outSpatialReference

The spatial reference of the output geometries. If not specified, the output geometries are in the spatial reference of the input geometries. If processSpatialReference is specified and outSpatialReference is not specified, the output geometries are in the spatial reference of the process spatial reference. See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<SpatialReference> outputSpatialReference

Deprecated at v2.0, use outSpatialReference instead.

<SpatialReference> processSpatialReference

The spatial reference that the model will use to perform geometry operations. If processSpatialReference is specified and outputSpatialReference is not specified, the output geometries are in the spatial reference of the process spatial reference. See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<Number> updateDelay

The time interval in milliseconds between each job status request sent to an asynchronous GP task.
Default value: 1000

<String> url

ArcGIS Server Rest API endpoint to the resource that receives the geoprocessing request.
Method Details

cancelJob(jobId, callback, errback)

Cancel an asynchronous geoprocessing job. Requires an ArcGIS Server 10.1 service or greater. (Added at v3.0)
Return type: Deferred
Parameters:
<String> jobId Required A string that uniquely identifies a job on the server. It is created when a job is submitted for execution and later used to check its status and retrieve the results.
<Function> callback Required The function to call when the method has completed. The arguments in the function are the same as the onJobCancel event.
<Function> errback Required An error object is returned if an error occurs during task execution.
Sample:

  gp.cancelJob(jobId, function (info) {

    console.log(info.jobStatus);

  });

 

cancelJobStatusUpdates(jobId)

Cancels the periodic job status updates initiated automatically when submitJob() is invoked for the job identified by jobId. You can still obtain the status of this job by calling the checkStatus() method at your own discretion. (Added at v1.1)
Parameters:
<String> jobId Required A string that uniquely identifies the job for which the job updates are cancelled.

checkJobStatus(jobId, callback?, errback?)

Sends a request to the GP Task for the current state of the job identified by jobId. Upon receiving the response, the onStatusUpdate event is fired and the optional callback function is invoked.
Return type: Deferred
Parameters:
<String> jobId Required A string that uniquely identifies a job on the server. It is created when a job is submitted for execution and later used to check its status and retrieve the results.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onStatusUpdate event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)

execute(inputParameters, callback?, errback?)

Sends a request to the server to execute a synchronous GP task. On completion, execute-complete event is fired and the optional callback function is invoked.
Return type: Deferred
Parameters:
<Object> inputParameters Required The inputParameters argument specifies the input parameters accepted by the task and their corresponding values. These input parameters are listed in the parameters field of the associated GP Task resource. For example, assume that a GP Task resource has the following input parameters:
  • < GPFeatureRecordSetLayer > Input_Points
  • < GPDouble > Distance
The parameters argument for the above inputs is a data object of the form:
{
 Input_Points: <FeatureSet>,
 Distance: <Number>
}
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the execute-complete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Sample:
require([
  "esri/Geoprocessor", "dojo/dom", ... 
], function(Geoprocessor, dom, ... ) {
  var gp = new Geoprocessor( ... );
  function executeGP(){
    var params = { "Input_Point":featureSet, "Days": dom.byId("days").value };
    gp.execute(params, displayTrack);
  }
  function displayTrack(results, messages) {
    //do something with the results
    var features = results[0].value.features;
  }
  ...
});

getResultData(jobId, parameterName, callback?, errback?)

Sends a request to the GP Task to get the task result identified by jobId and resultParameterName. On completion, the getresultdatacomplete event will be fired and the optional callback function will be invoked.
Return type: Deferred
Parameters:
<String> jobId Required The jobId returned from JobInfo.
<String> parameterName Required The name of the result parameter as defined in Services Directory.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onGetResultDataComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)

getResultImage(jobId, parameterName, imageParameters, callback?, errback?)

Sends a request to the GP Task to get the task result identified by jobId and resultParameterName as an image.
Return type: Deferred
Parameters:
<String> jobId Required The jobId returned from JobInfo.
<String> parameterName Required The name of the result parameter as defined in Services Directory.
<ImageParameters> imageParameters Required Specifies the properties of the result image.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onGetResultImageComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)

getResultImageLayer(jobId, parameterName?, imageParameters?, callback?)

Get the task result identified by jobId and resultParameterName as an ArcGISDynamicMapServiceLayer.
Parameters:
<String> jobId Required The jobId returned from JobInfo.
<String> parameterName Optional The name of the result parameter as defined in Services Directory. As of 3.9, the parameterName parameter is now also optional and shouldn't be passed a value if using 10.1 or greater.
<ImageParameters> imageParameters Optional Contains various options that can be specified when generating a dynamic map image.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onGetResultImageLayerComplete event.
Sample:
gp.getResultImageLayer(jobInfo.jobId, "Selected_Tax_Lot",imageParams, function(gpLayer){
  gpLayer.setOpacity(0.5);
  map.addLayer(gpLayer);
});

setOutSpatialReference(spatialReference)

Sets the well-known ID of the spatial reference of the output geometries.
Parameters:
<SpatialReference> spatialReference Required The well-known ID of a spatial reference.
{"wkid" : 4326} 
Sample:
gp.setOutSpatialReference({wkid:102100});

setOutputSpatialReference(spatialReference)

Deprecated at v2.0, use setOutSpatialReference instead.
Parameters:
<SpatialReference> spatialReference Required The well-known ID of a spatial reference.

setProcessSpatialReference(spatialReference)

Sets the well-known ID of the spatial reference that the model uses to perform geometry operations.
Parameters:
<SpatialReference> spatialReference Required The well-known ID of a spatial reference.
{"wkid" : 4326} 

setUpdateDelay(delay)

Sets the time interval in milliseconds between each job status request sent to an asynchronous GP task.
Parameters:
<Number> delay Required The value in milliseconds. One second equals 1000 milliseconds.
See also: updateDelay

submitJob(inputParameters, callback?, statusCallback?, errback?)

Submits a job to the server for asynchronous processing by the GP task. Once the job is submitted and until it is completed, the onStatusUpdate event is fired and the optional statusCallback() function is invoked at regular intervals, the duration of which is specified by the updateDelay property. Upon completion of the job, the onJobComplete event is fired and the optional callback function is invoked.

The task execution results can be retrieved using getResultData(), getResultImage() or getResultImageLayer() methods.
Return type: Deferred
Parameters:
<Object> inputParameters Required The inputParameters argument specifies the input parameters accepted by the task and their corresponding values. These input parameters are listed in the parameters field of the associated GP Task resource. For example, assume that a GP Task resource has the following input parameters:
  • < GPFeatureRecordSetLayer > Input_Points
  • < GPDouble > Distance
The parameters argument for the above inputs is a data object of the form:
 { Input_Points: <FeatureSet>, Distance: <Number> } 
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onJobComplete event.
<Function> statusCallback Optional Checks the current status of the job. The returned JobInfo message includes the status along with the GPMessage.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Sample:
require([
  "esri/tasks/Geoprocessor", "esri/layers/ImageParameters", ... 
], function(Geoprocessor, ImageParameters, ... ) {
  var gp = new Geoprocessor( ... );
  function executeGP() {
    var params = { "Total_value_greater_than":numval};
    gp.submitJob(params, completeCallback, statusCallback);
  }
  function statusCallback(jobInfo){
    console.log(jobInfo.jobStatus);
  }
  function completeCallback(jobInfo) {
    var imageParams = new ImageParameters();
    imageParams.imageSpatialReference = map.spatialReference;
    gp.getResultImageLayer(jobInfo.jobId, "Selected_Tax_Lot",imageParams, function(gpLayer){
      gpLayer.setOpacity(0.5);
      map.addLayer(gpLayer);
    });
  }
  ...
});
Event Details
[ On Style Events | Connect Style Event ]

error

Fires when an error occurs when executing the task. (Added at v3.6)
Event Object Properties:
<Error> error ArcGIS Server error message returned in a JavaScript error object.

execute-complete

Fires when a synchronous GP task is completed. Should be used in favor of onExecuteComplete. (Added at v3.5)
Event Object Properties:
<GPMessage[]> messages An array of GPMessage that has the type and description.
<ParameterValue[]> results An array of ParameterValue objects that gives access to the result parameters and the task execution messages.
See also: execute()

get-result-data-complete

Fires when the result of an asynchronous GP task execution is available. Should be used in favor of onGetResultDataComplete. (Added at v3.5)
Event Object Properties:
<ParameterValue> result Contains the result parameters and the task execution messages.
See also: getResultData()

get-result-image-complete

Fires when a map image is generated by invoking the getResultImage method. Should be used in favor of onGetResultImageComplete. (Added at v3.5)
Event Object Properties:
<MapImage> mapImage Contains the properties of a dynamically generated map image.

get-result-image-layer-complete

Fires when getResultImageLayer method has completed. Should be used in favor of onGetResultImageLayerComplete. (Added at v3.5)

job-cancel

Fires when the geoprocessing job is cancelled using the cancelJob method. The returned object includes the status and job id. Should be used in favor of onJobCancel. (Added at v3.5)
See also: cancelJob()

job-complete

Fires when an asynchronous GP task using submitJob is complete. Should be used in favor of onJobComplete. (Added at v3.5)
See also: submitJob()

status-update

Fires when a job status update is available. Should be used in favor of onStatusUpdate. (Added at v3.5)