Task operation: submitJob (REST)
When a geoprocessing service is published with asynchronous execution mode, the geoprocessing tasks of the service will support the Submit Job (submitJob) operation. The submitJob operation is suitable for long-running tasks, which processes 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, and for RasterData outputs that cannot be rendered by web applications. The outputs 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 applications.
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 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 below.
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 job status request will include jobId, jobStatus, and geoprocessing tool messages depending on the message level of the geoprocessing service. The JSON below shows the response sent by the server for 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 the jobStatus as esriJobExecuting. The other statuses of the job are described in the table below
jobStatus codes | Description |
esriJobWaiting | The server is busy with other requests. |
esriJobSubmitted | The server has accepted the job request. |
esriJobExecuting | The server is executing the job. |
esriJobSucceeded | The server has successfully completed the job and the output results are available. |
esriJobFailed | The job has 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 which can accessed using a URL. The server response of the status request will include information on the inputs and results URL. An example JSON response of a Buffer Points task with an output parameter Output_Polygons 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 results by using the respective resource URLs. 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/AMF/HTML output format based on client requests. An example JSON response for the output parameter Output_Polygons of data type GPFeatureRecordSetLayer is given below. Notice the response has the parameter 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 figure below sums up 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 results and inputs resources that can be accessed through the URL.
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 may 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 error response JSON of a failed task is shown below.
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 inputs and results 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 may decide to discard the submitJob operation anytime during the execution of the job and invoke Cancel operation on the job. The URL for Cancel job is http://<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 shown below.
JSON response of 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 cancel only for 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.