Asynchronous job processing

Some of the operations that are provided in the Web Services API may take a significant amount of elapsed time to complete. In order to optimize the usage of HMC session resources and to allow the client application the opportunity to perform other processing, such long-running operations are structured to be executed asynchronously (rather than synchronously) from the perspective of the client application.

In a synchronous operation, the Web Services API does not respond to the client application's request until all of the processing associated with the request is complete (successfully or in error) and the API can provide a final result status for the operation. The client application thread is typically blocked (not running) during this time.

By contrast, in a function that operates asynchronously by starting a job, the Web Services API performs just the minimal front-end validation and set up work needed to accept the request to perform the indicated operation, and then quickly returns an HTTP 202 (Accepted) result to the client indicating that the operation request has been started but is not yet finished. Along with the HTTP 202 (Accepted) result, the client application is provided with a URI that represents the asynchronous job that is in progress. This URI is of the form /api/jobs/{job-id}.

At any point after receiving the HTTP 202 (Accepted) result, the client application can invoke the Query Job Status operation described in this section to determine if the job has ended or not. A job is considered ended if it runs to completion or is canceled. If the job has not yet ended, the Query Job Status request returns an indication that the job is still running or cancellation has been requested. If the job has ended, the Query Job Status request returns an indication of how the job ended along with the final status code, reason code and result data associated with the now-finished asynchronous processing. Once a job ends, job status is retained by the HMC for a minimum of 4 hours to allow the client application time to retrieve the results, but this status and results are not held indefinitely.

Since the major reason an API operation is structured to be asynchronous is that it will take significant time to complete, very frequent polling for completion through calls to Query Job Status can lead to significant unproductive use of client application and HMC resources. In order to eliminate the need to poll at all, the Web Services API also provides asynchronous notifications of job completion or cancellation through its JMS and SSE notification capabilities. IBM® recommends that client applications use this notification facility to determine when a job has ended rather than polling. See Job completion notification for details on the JMS notification mechanism, or Job completion notification for SSE.

If it is not practical for a client application to use asynchronous notification of job completion, the application should introduce elapsed-time delays between successive Query Job Status requests to poll the current job status in order to reduce unproductive use of resources.