This topic describes the work requests feature documented in the Work Requests 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 list.
- Classic Migration Service: View the State of a Work Request
- Application Performance Monitoring: Work Request API
- Bastion: WorkRequest API
- Blockchain Platform: Integration: Work Requests
- Cloud Advisor: Work Request API
- Content Management: Work Request API
- Data Catalog: Work Requests
- Data Integration: Work Requests
- Data Labeling: Work Requests
- Data Science: Creating Notebook Sessions and Deleting Projects
- Database Management: Work Request API
- Database Migration: WorkRequest API
- Database Tools: Work Request Reference
- DevOps: Work Request Reference
- GoldenGate: WorkRequest Reference
- IAM: To delete a compartment and Deleting Tag Key Definitions and Namespaces
- Java Management: WorkRequest API
- Load Balancing: Work Request Management
- Logging Analytics: WorkRequest API
- Management Agent: WorkRequest API
- Object Storage: Copy Object Work Requests
- Service Connector Hub: Viewing the State of a Work Request
- Vulnerability Scanning: WorkRequest API
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
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.
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.
- You call the
LaunchInstanceendpoint in the Compute API.
- Synchronous validation occurs, and you receive an HTTP 2xx response from the Compute API that includes the OCID of the work request in the
- When the create instance workflow initiates, asynchronous validation occurs throughout the workflow. An error occurs, and the validation fails.
- The Compute API populates the work request errors and marks the work request as failed.
- To monitor the work request, you call
GetWorkRequestin the Work Requests API and pass in the work request ID found in the
- Seeing that the work request failed, you call
ListWorkRequestErrorsin the Work Requests API and pass in the work request ID to retrieve a list of errors.
- The Work Requests API returns a list of errors that you can use to determine the cause of the failure.
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.
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.
- If the resource is displayed in a list view, click the resource name to view the resource details.
- Under Resources, 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 menu 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: