This topic describes the work requests feature documented in the Work Requests API. The following Oracle Cloud Infrastructure services are integrated with this API:
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 topics:
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.
If an operation fails, a work request can help you determine which step of the process had an error.
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 is done.
Work requests are retained for 12 hours.
To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment you should 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
Work Request States
Note: Work requests for some services or operations may support only a subset of the following statuses.
- The request is in the work request queue to be processed.
- A work request record exists for the specified request, but there is no associated WORK_COMPLETED record.
- A work request record exists for this request and an associated WORK_COMPLETED record has the state SUCCEEDED.
- A work request record exists for this request and an associated WORK_COMPLETED record has the state FAILED.
- The work request is in the process of canceling.
- The work request has been canceled.
The steps to view a work request are similar for Oracle Cloud Infrastructure services that support work requests.
Navigate to resource whose work requests you want to see.
For example, to see the work requests for a Compute instance: Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
- If the resource is displayed in a list view, click the resource name to view the resource details.
- In the Resources section of the details page, click Work Requests. The status of all work requests appears on the page.
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 icon (three dots) next to a resource to copy the resource's OCID.
Using the API
For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.
Use these API operations to monitor the state of work requests: