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
Properties
Methods
cancelJob(jobId, callback, errback) | Deferred | Cancel an asynchronous geoprocessing job. |
cancelJobStatusUpdates(jobId) | None | Cancels the periodic job status updates initiated automatically when submitJob() is invoked for the job identified by jobId. |
checkJobStatus(jobId, callback?, errback?) | Deferred | Sends a request to the GP Task for the current state of the job identified by jobId. |
execute(inputParameters, callback?, errback?) | Deferred | Sends a request to the server to execute a synchronous GP task. |
getResultData(jobId, parameterName, callback?, errback?) | Deferred | Sends a request to the GP Task to get the task result identified by jobId and resultParameterName. |
getResultImage(jobId, parameterName, imageParameters, callback?, errback?) | Deferred | Sends a request to the GP Task to get the task result identified by jobId and resultParameterName as an image. |
getResultImageLayer(jobId, parameterName?, imageParameters?, callback?) | ArcGISDynamicMapServiceLayer | Get the task result identified by jobId and resultParameterName as an ArcGISDynamicMapServiceLayer. |
setOutSpatialReference(spatialReference) | None | Sets the well-known ID of the spatial reference of the output geometries. |
setOutputSpatialReference(spatialReference) | None | Deprecated at v2.0, use setOutSpatialReference instead.. |
setProcessSpatialReference(spatialReference) | None | Sets the well-known ID of the spatial reference that the model uses to perform geometry operations. |
setUpdateDelay(delay) | None | Sets the time interval in milliseconds between each job status request sent to an asynchronous GP task. |
submitJob(inputParameters, callback?, statusCallback?, errback?) | Deferred | Submits 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.
Constructor Details
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
https://sampleserver6.arcgisonline.com/arcgis/rest/services/Viewshed/GPServer. 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("https://www.example.com/argis/rest/services/Specialty/ESRI_Currents_World/GPServer/MessageInABottle");
...
});
Property Details
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.
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.
The time interval in milliseconds between each job status request sent to an asynchronous GP task.
Default value: 1000
ArcGIS Server Rest API endpoint to the resource that receives the geoprocessing request.
Method Details
Cancel an asynchronous geoprocessing job. Requires an ArcGIS Server 10.1 service or greater. (Added at v3.0)
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);
});
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. |
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.
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) |
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.
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;
}
...
});
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.
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) |
Sends a request to the GP Task to get the task result identified by jobId and resultParameterName as an image.
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) |
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);
});
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});
Parameters:
<SpatialReference > spatialReference |
Required |
The well-known ID of a spatial reference. |
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}
|
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. |
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.
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 ]
Fires when an error occurs when executing the task. (Added at v3.6)
Fires when a synchronous GP task is completed. Should be used in favor of onExecuteComplete. (Added at v3.5)
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. |
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. |
Fires when getResultImageLayer method has completed. Should be used in favor of onGetResultImageLayerComplete. (Added at v3.5)
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)
Fires when an asynchronous GP task using submitJob is complete. Should be used in favor of onJobComplete. (Added at v3.5)
Fires when a job status update is available. Should be used in favor of onStatusUpdate. (Added at v3.5)
Fires when an error occurs when executing the task. (Added at v1.3)
Fires when a synchronous GP task is completed.
Fires when the result of an asynchronous GP task execution is available.
Event Object Properties:
<ParameterValue > result |
Contains the result parameters and the task execution messages. |
Fires when a map image is generated by invoking the getResultImage() method.
Event Object Properties:
<MapImage > mapImage |
Contains the properties of a dynamically generated map image. |
Fires when getResultImageLayer() has completed.
Event Object Properties:
<Layer > ArcGISDynamicMapServiceLayer |
The layer that can be added to the map. |
Fires when the geoprocessing job is cancelled using the cancelJob
method. The returned object includes the status and job id. (Added at v3.0)
Event Object Properties:
<Object > status |
An object that includes the status and job id.
{
"jobId":"j5f0cf6f3d33544b4a968aac44d259128",
"jobStatus":"esriJobCancelled"
}
|
Sample:
dojo.connect(gp,'onJobCancel',function(response){
console.log("Job Cancelled " + dojo.toJson(response));
});
Fires when an asynchronous GP task using submitJob is complete.
Fires when a job status update is available.