Asynchronous operations

Most requests to the OpenText Core Software Delivery Platform REST API are processed synchronously: the server performs the operation and returns the result in the same response. Some operations, however, are processed asynchronously.

Synchronous operations

In a synchronous operation, the server completes the work while handling the request and returns the outcome directly in the response. This is the common case, and it is what you can expect for most requests.

Asynchronous operations

An operation that could take a long time to finish is processed asynchronously, so that the request does not have to stay open while the work runs. Instead of performing the work immediately, the server schedules it to run in the background and returns a background task that represents the scheduled work. The response contains the ID of that background task.

You then track the operation as follows:

  1. Send the request. The response contains the ID of the background task.

  2. Poll the background task periodically to check its status.

  3. When the task is complete, the response indicates whether the operation succeeded or failed.

Reading a background task

A background task is itself an entity, in the workspace-scoped background_tasks collection. Read it by its ID, as you would any entity, to check its progress:

GET /api/shared_spaces/{shared_space_id}/workspaces/{workspace_id}/background_tasks/{id}?fields=status,result,correlation_id

The relevant fields are:

  • status. The state of the task: NotScheduled, Scheduled, Running, Finished, Error, or WaitTimeExceeded.

  • result. The outcome of the task, available once it has finished.

  • correlation_id. An identifier you can quote when reporting a problem. See Diagnostics and troubleshooting.

Poll until status is Finished or Error, then read the result. Space out your polls rather than requesting continuously.

When operations run asynchronously

Operations that act on many entities at once, such as creating, updating, or deleting entities in bulk, may run asynchronously. Processing such an operation in the background avoids the request timing out and limits its impact on the server.

Note: For bulk entity operations, the asynchronous behavior is typically transparent: you send the request in the same way as a synchronous one, and the server decides whether to process it in the background.

See also