Ctrl+K

Introduction to Operations

Introduction to Operations#

Workiva’s Operations track the status of asynchronous requests, which are commonly used for edits on the platform.

Typically, you will use this pattern when using Operations:

  1. Make an asynchronous edit and receive a 202 response.

  2. Poll the operation until a completed status is returned.

  3. Follow the completed operation’s resourceUrl to learn more about the edit.

In this guide, you will walk through a typical operation flow.

Example Use Case#

Suppose you’ve issued an edit and received back a 202 response. In the Workiva platform, this response will always have Location and Retry-After headers.

Response Headers#
...
Location: https://api.app.wdesk.com/prototype/platform/operations/f6737d79-ed31-4657-b863-5d18506d2fe1
Retry-After: 5
...

You can now poll the resource identified by the Location header until it indicates success.

Request#
curl -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/operations/f6737d79-ed31-4657-b863-5d18506d2fe1
Response#
{
    "id": "f6737d79-ed31-4657-b863-5d18506d2fe1",
    "status": "started",
    "created": {
        "dateTime": "2024-12-13T16:45:21Z"
    },
    "updated": {
        "dateTime": "2024-12-13T16:48:55Z"
    },
    "originalRequest": "d4e3353d-2c60-49f0-b1c3-53dd17638143"
}

The response above shows that the operation has started but has not yet completed.

Check the response headers for a Retry-After header and try again after that many seconds.

Response Headers#
...
Retry-After: 5
...

The Retry-After: 5 response indicates that you should wait five seconds before polling the operation again.

Five seconds later, you might get the following response.

Response#
{
    "id": "f6737d79-ed31-4657-b863-5d18506d2fe1",
    "status": "completed",
    "resourceUrl": "https://api.app.wdesk.com/prototype/platform/content/richText/WA8jJy8nLubbkEHM99i4dIuJ4CNQDsW8rB7MvLmwCHucbKj61j6tmTLBft2g/anchors/WA2RlYGVnFRpIvN9ARJyvkFDKumaxA992ZtQGdnN6wrFWpmIwHPRnU9BgLtBdmBt6WU?$revision=2c6438ab45406bb6",
    "created": {
        "dateTime": "2024-12-13T16:45:21Z"
    },
    "updated": {
        "dateTime": "2024-12-13T16:48:55Z"
    },
    "originalRequest": "d4e3353d-2c60-49f0-b1c3-53dd17638143"
}

The status: completed response indicates that your requested operation has completed. Most completed operations provide a resourceUrl. Querying this resource will give you additional edit-specific information about the result of your edit.

Frequently Asked Questions#

What statuses indicate that my operation is not yet complete?#

The acknowledged, queued, and started statuses indicate that the operation is not complete.

What statuses indicate that my operation has completed successfully?#

Only the completed status indicates that the operation completed successfully.

What should I do if my operation’s status is failed?#

Failed operations typically have a details field with more information about the failure. A failed operation must be initiated anew by whatever endpoint was originally used to create it.

Do I have to poll an operation until it is completed?#

Your operation will complete regardless of whether you poll for its status. However, if an operation fails, you are likely to want to take corrective action. For example, if you make three different edit requests and the first fails, your document is likely to be in a state you do not expect.