Work requests help you monitor long-running operations such as database backups or the provisioning of compute instances.
When you start a long-running operation, the service creates a work request. A work request is an activity log that lets you track each step in the operation's progress. Each work request has an OCID that lets you interact with it programmatically and use it for automation.
Work requests typically provide information about the status of the associated workflow, errors, log files, and a list of resources that are affected by the workflow.
Some Oracle Cloud Infrastructure services, such as Compute and Database, support work requests using the Work Requests API, which contains the
Some services offer work requests supported by the service API rather than the Work Requests API discussed in this topic. These service APIs each include operations that work in a similar manner to the
GetWorkRequest operation used by the Work Requests API.
See the reference documentation for each service's work request API for details. Links to each are provided in the More Information and APIs for Supported Services section.
Getting Started with Work Requests
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 the instance pool workflow has finished.
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: The permissions that allow users to view the work requests, logs, and error messages for an operation vary depending on the service. For some services, work requests inherit the permissions of the operation that spawns the work request. For other services, work requests require separate permissions. For more information, see Policy Reference.
If you're new to policies, see Getting Started with Policies and Common Policies.
Work Request Status
Work requests provide visibility into the progress of long-running, asynchronous operations. The status of a work request indicates the progress of the operation.
Statuses typically include values such as
SUCCEEDED. Because each service or operation that supports work requests provides its own API for obtaining status, the specific values that are returned in a work request can vary depending on the service and operation. For information about the status attributes that are supported by work requests for each service, see Work Request Status.
Troubleshooting Validation Errors
Work requests capture asynchronous validation failures. If an asynchronous operation fails, a work request can help you determine where in the process the error occurred.
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 and are returned by the work request. A successful call to the service API that returns an HTTP 200 response ("request was successful") might be followed by an asynchronous error that is captured by the work request.
For example, when you create a compute instance, an API call is made to the
LaunchInstance operation. At this point, synchronous validation occurs. If a failure occurs, an HTTP 4xx response is returned. If the call succeeds, an HTTP 200 response is returned and the create instance workflow starts.
While the create instance workflow continues, additional validation and error checks occur, and an asynchronous work request is created to track the progress of the workflow. The response to the
LaunchInstance operation contains the OCID of the work request in the
opc-work-request-id header. You can monitor the status of the work request at any time by calling the
GetWorkRequest operation and passing in the work request ID. If an error occurs during the workflow, you can retrieve a list of errors by calling
ListWorkRequestErrors and passing in the work request ID.
The work request itself remains in a queue until the operation has completed.
For detailed information about 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. The response includes the OCID of the work request in the
- The create instance workflow starts, and 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 might vary depending on the service and the resource whose work requests you want to see.
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.
More Information and APIs for Supported Services
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 the following API operations to monitor the state of work requests:
- Application Performance Monitoring work request API
- Autonomous Recovery Service work request API
- Bastion work request API
- Blockchain Platform work requests
Classic Migration Service:
- Cloud Advisor work request API
- Compute work request API
- Container Engine for Kubernetes work request API
- Container Instances work request API
- Content Management work request API
- Data Integration work request API
- Database work request API
- Database Management work request API
- Database Migration work request API
- Database Tools work request API
- DevOps work request API
- Full Stack Disaster Recovery work request API
- GoldenGate work request API
- Integration work request API
- Java Management work request API
- Logging Analytics work request API
- Management Agent work request API
- MySQL Database work request API
- Network Firewall work request API
- Oracle Cloud Bridge work request API
- Oracle Cloud Migrations work request API
- Process Automation work request API
- Queue work request API
- Resource Manager work request API
Service Connector Hub:
- Service Mesh work request API
- Stack Monitoring work request API
- Vision work request API
- Visual Builder Studio: WorkRequest API
- Vulnerability Scanning work request API