Oracle Cloud Infrastructure Documentation

Work Requests

This topic describes the work requests feature documented in the Work Requests API.

Note

Some Oracle Cloud Infrastructure services offer work requests supported by the service API rather than the Work Requests API discussed in this topic. For information about work requests in these services, see the following list.

Services with their own work request APIs

Getting Started with Work Requests

Work requests allow you to monitor long-running operations such as database backups or the provisioning of compute instances. When you launch such an operation, the service spawns a work request. A work request is an activity log that enables you to track each step in the operation's progress. Each work request has an OCID  that allows you to interact with it programmatically and use it for automation.

Work requests are helpful in the following scenarios:

  • If an operation fails, a work request can help you determine which step of the process had an error. Work requests capture asynchronous validation failures.
  • Some operations affect multiple resources. For example, creating an instance pool also affects instances and instance configurations. A work request provides a list of the resources that an operation affects.
  • For workflows that require sequential operations, you can monitor each operation’s work request and confirm that the operation has completed before proceeding to the next operation. For example, say that you want to create an instance pool with autoscaling enabled. To do this, you must first create the instance pool, and then configure autoscaling. You can monitor the work request for creating the instance pool to determine when that workflow is complete, and then configure autoscaling after it completes.

Work requests are retained for 12 hours.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: Work requests inherit the permissions of the operation that spawns the work request. To enable users to view the work requests, logs, and error messages for an operation, write a policy that grants users permission to do the operation. For example, to let users see the work requests associated with launching instances, write a policy that enables users to launch instances.

To enable users to list all work requests in a tenancy, use the following policy:

Allow group SupportTeam to inspect work-requests in tenancy

If you're new to policies, see Getting Started with Policies and Common Policies.

Work Request States

Note: Work requests for some services or operations may support only a subset of the following statuses.

ACCEPTED
The request is in the work request queue to be processed.
IN_PROGRESS
A work request record exists for the specified request, but there is no associated WORK_COMPLETED record.
SUCCEEDED
A work request record exists for this request and an associated WORK_COMPLETED record has the state SUCCEEDED.
FAILED
A work request record exists for this request and an associated WORK_COMPLETED record has the state FAILED.
CANCELING
The work request is in the process of canceling.
CANCELED
The work request has been canceled.

Troubleshooting Validation Errors

If an operation fails, a work request can help you determine where in the process the error occurred. Work requests capture asynchronous validation failures. Synchronous errors occur during the initial call to the service API and are returned by the service API. Asynchronous errors occur during the workflow that occurs after the initial API call. A successful call to the service API that returns an HTTP 200 response might be followed by an asynchronous error captured by the Work Requests API.

For example, when you create a compute instance, an API call is made to the Compute API. At this point, synchronous validation occurs. If the call succeeds, and HTTP 200 response is returned to the user. If a failure occurs, an HTTP 4xx response is returned. The response to the REST API call contains the OCID of the work request in the opc-work-request-id header. The OCID is the work request ID, which you can use to get the status of the associated workflow, error information, and log files from the Work Requests API.

While the create instance workflow continues, an asynchronous work request is spawned, and additional validation and error checks occur. The asynchronous work request provides visibility into the progress of long-running, asynchronous operations. The work request itself remains in a queue until the operation has completed.

You can monitor the status of the work request at any time by calling GetWorkRequest in the Work Requests API and passing in the work request ID found in the opc-work-request-id header. If an error occurs during the workflow, you can call ListWorkRequestErrors in the Work Requests API and pass in the work request ID to retrieve a list of errors.

For detailed information about asynchronous work requests, including how to filter the request response and a sample request and response, see Asynchronous Work Requests.

Example Work Request Validation Workflow

The following diagram shows an example create instance workflow in which the synchronous validation succeeds and the asynchronous validation fails.

  1. You call the LaunchInstance endpoint in the Compute API.
  2. Synchronous validation occurs, and you receive an HTTP 2xx response from the Compute API that includes the OCID of the work request in the opc-work-request-id header.
  3. When the create instance workflow initiates, asynchronous validation occurs throughout the workflow. An error occurs, and the validation fails.
  4. The Compute API populates the work request errors and marks the work request as failed.
  5. To monitor the work request, you call GetWorkRequest in the Work Requests API and pass in the work request ID found in the opc-work-request-id header.
  6. Seeing that the work request failed, you call ListWorkRequestErrors in the Work Requests API and pass in the work request ID to retrieve a list of errors.
  7. The Work Requests API returns a list of errors that you can use to determine the cause of the failure.
High level create instance workflow showing synchronous and asynchronous validation.

Using the Console to View Work Requests

You can use the Console to see the log messages, error messages, and resources associated with a specific work request. The steps to view a work request are similar for Oracle Cloud Infrastructure services that support work requests.

  1. Navigate to the resource whose work requests you want to see.

    For example, to see the work requests for a compute instance: Open the navigation menu and click Compute. Under Compute, click Instances.

  2. If the resource is displayed in a list view, click the resource name to view the resource details.
  3. Under Resources, click Work Requests. The status of all work requests appears on the page.

  4. To see the log messages, error messages, and resources that are associated with a specific work request, click the operation name. Then, select an option in the More information section.

    For associated resources, you can click the the Actions menu next to a resource to copy the resource's OCID.