Pending Actions (Server Jobs)

Pending Action records is how we track job progress and results. Most actions will return a Pending Action ID that you can use to check the status of the job. As a result, it's important to understand how to use the Pending Action API.

Data model

Below is the data model for a Pending Action record. These records are one of our oldest and don't have a tidied up v3 variant yet.

When checking for completion, you can see if the .Status stops equaling IN_PROGRESS.

The Result property is the primary candidate for a v3 overhaul where it returns a stringified JSON object you have to parse yourself.
This is the result of us migrating from a singular result line to a more complex result object. Some of our oldest jobs may return a non-JSON string in this field.

/**
 * Available Pending Action statuses.
 */
export enum EStatus {
    InProgress = "IN_PROGRESS",
    Cancelled = "CANCELLED",
    Complete = "COMPLETE",
    Failed = "FAILED"
}

/**
 * The Pending Action record itself.
 */
interface IAction {
    // ID of the Pending Action record.
    ID: number;
    // ID of the application that created the Pending Action.
    "CreatedBy.Application": string;
    // ID of the user that created the pending action.
    "CreatedByUser.ID": string;
    // Result string is a stringified JSON object.
    // This is not always the case so please check the data before parsing it.
    Result: string;
    // Progress % of the pending action.
    Progress: number;
    // Description on why the Pending Action was started.
    Description: string;
    // Status of the Pending Action.
    Status: EStatus;
    // Created/updated/completed date/time in ISO 8601 UTC.
    Created: string;
    Updated?: string;
    Completed?: string;
}

Request the record

We recommend requesting the Pending Action record every 5 seconds until it's marked as no longer in progress.

// Response is the same as IAction definition above.
// It returns the JSON directly.

Request progress messages

If you'd like expanded information about the progress of a Pending Action, you can request for progress messages.

interface IResponse {
    // Array of progress messages found for your search.
    Items: {
        // ID of the pending action record.
        "PendingAction.ID": number;
        // ID of the message record.
        ID: number;
        // ID of the application that created the message.
        "CreatedBy.Application": string;
        // Date/time the message was created.
        "Created": string;
        // Message type. Certain types can be hidden from end-users as they are only used for debugging.
        "Message.Type": string;
        // Message text.
        Message: string;
    }[];
}

Cancel a Pending Action

If you need to cancel a Pending Action, you can do so with this request.