Skip To Content

Task operation: submitJob (REST)

When a geoprocessing service is published with asynchronous execution mode, the geoprocessing tasks of the service will support the (submitJob) operation. The submitJob operation is suitable for long-running tasks that process large datasets. Also, the geoprocessing server can create a result map service for a successful job operation. Hence, the submitJob operation is suitable for nontransportable tool outputs, such as TIN, CAD, and so on, as well as RasterData outputs that cannot be rendered by web apps. The output in such cases can be rendered as a result map service by the server, and clients can add the result map service to their web apps.

Submitting a job using submitJob

The URL template for submitJob operation is http://<gp-task-url>/submitJob. The client sends a request to run the task through the submitJob operation. When submitting a job, the input parameters of the task are constructed as a URL and sent to the server, similar to the executeTask operation. When the server receives a request for a submitJob operation, it creates a job resource with a unique ID known as jobId and returns it to the client. The server response of the geoprocessing task submitJob operation will have a unique job identifier (jobId) and the job status (jobStatus) as shown in the following code sample:

JSON response of submitJob request

{ "jobId" : "ja892cd2a90d149db9a171fc86ff530b4",
               "jobStatus": "esriJobSubmitted"}

Verifying status of the job

The URL of the job resource is http://<task-url>/jobs/<jobId>. The client can periodically send requests through the job URL and determine the status of the job. The server response for the job status request will include jobId, jobStatus, and geoprocessing tool messages depending on the message level of the geoprocessing service. The following JSON shows the response sent by the server for a status request. Notice each message has a type and description property.

JSON response of status request


{
 "jobId": "ja892cd2a90d149db9a171fc86ff530b4",
 "jobStatus": "esriJobExecuting",
 "messages": [
  {
   "type": "esriJobMessageTypeInformative",
   "description": "Submitted."
  },
  {
   "type": "esriJobMessageTypeInformative",
   "description": "Executing..."
  }
 ]
}

The example above shows jobStatus as esriJobExecuting. The other status codes of the job are described in the following table:

jobStatus codesDescription

esriJobWaiting

The server is busy with other requests.

esriJobSubmitted

The server accepted the job request.

esriJobExecuting

The server is executing the job.

esriJobSucceeded

The server successfully completed the job and the output results are available.

esriJobFailed

The job failed to execute because of invalid parameters or other geoprocessing tool failures.

esriJobCancelling

The server is cancelling the execution of the job based on the client's request.

esriJobCancelled

The request to run the job was cancelled by the client, and the server terminated the job execution.

Successful task result

When the job has succeeded (jobStatus = esriJobSucceeded) the server creates new resources for the input and output parameters that can be accessed using a URL. The status request response from the server will include information on the inputs and results URLs. An example JSON response of a Buffer Points task with anOutput_Polygons output parameter is shown below. Notice that the value of the output and input parameters is a relative URL contrary to the result value of an execute task.

JSON response of a successful task result


{
 "jobId": "ja892cd2a90d149db9a171fc86ff530b4",
 "jobStatus": "esriJobSucceeded",
 "results": {
  "Output_Polygons": {
   "paramUrl": "results/Output_Polygons"
  }
 },
 "inputs": {
  "Input_Features": {
   "paramUrl": "inputs/Input_Features"
  }
 },
 "messages": [ 
 ]
}

At the end of successful job completion, the client must send a request to retrieve each output parameter. The client can get the input or output result using the respective resource URL. The result URL is http://<job-url>/results/<param-name>. The inputs URL is http://<job-url>/inputs/<param-name>. The response from these resources will be the value of the parameter, and it can be in any JSON, KML, or HTML output format based on client requests. A sample JSON response for the Output_Polygons output parameter of data type GPFeatureRecordSetLayer is shown below. Notice the response has the name, data type, and value of the parameter.

JSON response of result output parameter

{
 "paramName": "Buffer_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.499937415,
     684676.8331969082
    ],
    [
     7643683.927544653,
     684675.5310036391
    ] ...more
   
   ]]}
  }],
  "exceededTransferLimit": false
 }
}

The following image summarizes the server/client communication of a submitJob operation. Notice the periodic status requests sent by the client to determine the status of the job. The client can determine the duration between each status request. When the server has successfully completed the execution of the job, it creates the result and input resources that can be accessed through the URL.

submitJob operation: server/client communication

Also, if the geoprocessing service has been published with View result with a map service enabled, the server creates a result map service of the output parameters at the end of the successful task execution. Each geodataset output parameter of the task will correspond to a layer in the map service and will be drawn based on the layer symbology defined for the parameters in the tasks.

Error response

A job can fail because of invalid input parameters, inaccessible project data, or other geoprocessing failures. When a job has failed, the status of the job will be updated to esriJobFailed. The client must verify the status of the job using the job URL to keep track of job failures. The following is an error response JSON of a failed task:

Status response JSON with esriJobFailed status

{
 "jobId": "ja892cd2a90d149db9a171fc86ff530b4",
 "jobStatus": "esriJobFailed",
 "messages": [
  {
   "type": "esriJobMessageTypeInformative",
   "description": "Submitted."
  },
  {
   "type": "esriJobMessageTypeInformative",
   "description": "Executing..."
  },
  {
   "type": "esriJobMessageTypeError",
   "description": "Failed."
  }
 ]
}

When a job has failed, the server will not create input and result resources. Also, the server cannot create a result map service even if the geoprocessing service has an accompanying result map service.

Cancel job

The client can discard the submitJoboperation anytime during the execution of the job and invoke the Cancel operation on the job. The URL for the Cancel operation is https://<gp-task-url>/cancel. When the server receives a cancel request, it modifies the job status to esriJobCancelling and attempts to terminate the execution of the job. The server returns a job status message to the client as follows:

JSON response to a cancel request


{
 "jobId": "ja892cd2a90d149db9a171fc86ff530b4",
 "jobStatus": "esriJobCancelling"
}

The client can continue to poll the status of the job using the job URL and track the progress of job cancellation. Also, a client can request to cancel only jobs that are in esriJobWaiting, esriJobSubmitted, or esriJobExecuting status. If the cancel request is issued for jobs in esriJobSucceeded or esriJobFailed status, an error message will be returned by the server.

Related topics