Hide Table of Contents
Running a geoprocessing task and getting the results

The way that you run a geoprocessing task and get the results varies depending on the execution type of the geoprocessing task, which can be either synchronous or asynchronous. In ArcGIS Server, synchronous geoprocessing services return the results of each operation to the client as soon as the operation is complete - no results are stored on the server. Alternatively, asynchronous services store results on the server and return a job ID to the client. The client can then use this ID to retrieve the results at a convenient time. Synchronous services are intended for geoprocessing operations that take a short amount of time to execute (e.g. less than 3 seconds), while asynchronous services should be used for longer-running operations.

The Services Directory page for the task can tell you the execution type. If the Supported Operation of the task is "Execute task" then it's a synchronous task. If the Supported Operation is "Submit Job", the task is asynchronous.

The server administrator sets the execution type of a geoprocessing service. If you are the server administrator, you should choose synchronous for tasks that can run quickly or tasks that do not have a result map service. You should choose asynchronous for tasks that have a result map service or tasks that take longer to run. Asynchronous tasks ensure that browser time-outs will not interfere with the geoprocessing job.

Running a synchronous task and getting the results

To run a synchronous task, call Geoprocessor.execute(). You need to supply the input parameters for the task and a callback function that tells the application how to handle the results.

gp.execute(params, drawViewshed);

The results of the task are returned to the callback function as an array of ParameterValue. If the server administrator has enabled messages, you will also get an array of GPMessage objects.

The number and types of items in the result ParameterValue array will vary depending on the number of model output parameters and their data types. If you want to know which JavaScript objects to expect in the array, see the parameters table.

You can loop through each item in the results array and add it to the map, write its attributes on the screen, or do whatever is appropriate. The following code is an example of how you can loop through one FeatureSet returned by a model and add the features to the map. This code also writes the geoprocessing messages to the web browser's developer tools console window for informational purposes.

function drawViewshed(results, messages) {

   //Write messages to the debug console
   var description;

   for (var m=0, ml=messages.length; m<ml; m++) {
      description = messages[m].description;
      console.log(description);
   }

   // Draw results
   var polySymbol = new esri.symbol.SimpleFillSymbol();
   var features = results[0].value.features;
   for (var f=0, fl=features.length; f<fl; f++) {
      var feature = features[f];
      feature.setSymbol(polySymbol);
      map.graphics.add(feature);
   }

}

Running an asynchronous task and getting the results

To run an asynchronous task, call Geoprocessor.submitJob(). You need to supply the input parameters for the task. You can also specify a "complete callback" function to be called when the job is successful, and a "status callback" function to be called every time the geoprocessor checks the status of the job.

gp.submitJob(params, completeCallback, statusCallback);

By default the status is checked once per second. Each time the status is checked, the status callback function is called. You can change the status check interval through the Geoprocessor.setUpdateDelay() method.

The status callback receives a JobInfo object containing the job ID, the job status, and any GPMessages returned by the geoprocessor (if the server administrator has enabled messages). You may choose to write this information to the console window or elsewhere to track the status of the job.

function statusCallback(jobInfo) {
  console.log(jobInfo.jobStatus);
}

When JobInfo.jobStatus = STATUS_SUCCEEDED the complete callback function will be called. In this callback, you can get the results of the job by calling Geoprocessor.getResultData(). You'll generally supply three parameters in this method call:

  1. The job ID. You can get this from the JobInfo object received by the callback function.
  2. The output parameter name that you want to retrieve. Check the Services Directory page for the task if you're unsure of the parameter name.
  3. A callback function that does something with the result. The result will be passed to this function as a ParameterValue object. The type of data contained in this object will vary depending on the output parameter type you retrieved. See the parameters table for a list of types to expect.

The code below shows a complete callback that calls getResultData for one parameter (a FeatureSet) then uses another callback function to draw the results on the map.

function completeCallback(jobInfo) {
  console.log("getting data");
  gp.getResultData(jobInfo.jobId, "Viewshed_Result", displayResult);
}

function displayResult(result, messages) {
  var simpleLineSymbol = new esri.symbol.SimpleLineSymbol(esri.symbol.SimpleLineSymbol.STYLE_SOLID,
          new dojo.Color([255,255,0]), 1);
  var features = result.value.features;
  for (var f=0, fl=features.length; f<fl; f++) {
    var feature = features[f];
    feature.setSymbol(simpleLineSymbol);
    map.graphics.add(feature);
  }
}

You can call getResultData multiple times if you have several output parameters you want to retrieve.

It's possible that the server administrator has configured the task to draw the results on the server instead of streaming the results to the client. In this scenario the task is said to have a result map service. Instead of calling Geoprocessor.getResultData(), you should call Geoprocessor.getResultImageLayer(), which returns an ArcGISDynamicMapServiceLayer containing the results. You can add this layer to the map in a callback function.

function completeCallback(jobInfo) {
  console.log("getting data");
  var imageParams = new esri.layers.ImageParameters();
  gp.getResultImageLayer(jobInfo.jobId, "Viewshed_Result",imageParams, displayResult);
}

function displayResult(layer) {
  map.addLayer(layer);
}

Alternatively, you can call Geoprocessor.getResultImage(). This gives you a static image instead of a map layer. The image cannot be added to the map.