Skip to content

Undo and the Undo Queue

Most AmpliFi operations are performed synchronously. When the API call returns the operation has either completed successfully or it has failed.

Other operations may take an indeterminate amount of time. For example, a request for approval from a backoffice may take hours or more. In these cases it may be necessary to check later on the status of the request, or a websocket may be used to notify the caller when the operation is complete.

A few actions, however, are brief but asynchronous. These actions may be delayed for a short time after the call returns, and during this time they may be cancelled. This is accomplished by placing the requests in an undo queue. Each entry in the queue is assigned a unique identifier, along with a time that must pass before it may be executed. The specific time limit depends on the type of action. These actions are considered undoable; an undo operation may be used to cancel them within a specified time limit.

When a request is made for an action that is considered undoable, an undo queue object will be placed in the queue that includes a time limit that must pass before the entry is actionable. The entry is marked actionable when the time limit expires.

The queue is scanned at regular intervals, 100 ms by default. On each scan, each entry that is marked actionable will be performed. If the action succeeds, the entry is then removed from the queue. If the action fails, the entry may be put back in the queue up to a specified number of times.

The Undo API (see below) may be called to cancel an action that has not yet begun to be performed. The undone action is removed from the queue. This may be done even after the entry is marked actionable.

AmpliFi also provides methods to expedite the execution of one or more actions in the queue. These methods mark the entries actionable immediately regardless of their time limit.

Note that AmpliFi does not provide a means to undo actions that have already been performed. The undo queue simply enables actions to be briefly delayed, and while they are delayed they may possibly be cancelled.

The Undo Queue Object

An undoable action is represented in the queue by an undo queue object. This table gives the properties contained in this object.

Property Type Required? (default) Description
id string yes AmpliFi Id (handle) of the undo object
AFiUserId string yes AmpliFId of the current user
userId string yes copy of AFiUserId
name string yes name of the action to be performed
secsUntilActionable number yes time until the action can be performed
redoOnError number yes number of retries permitted in case of error
payload object yes data required to perform this action
action function yes function to be called to perform this action
onError function yes function to be called if an error occurs
onUndo function yes function to notify the user if the action is cancelled
onSuccess function yes function to notify the user if the action completed successfully
dtsQueued dts yes Date/time item was placed in the queue

The Undo Response Object

If an action is undoable, the response to the request for that action will contain an undo response object to enable the optional undo. The properties of this object are:

Property Type Required? (default) Description
id string yes undo handle
isActionable boolean yes true if the action can be performed immediately
dtsQueued dts yes date/time the item was queued
dtsExpiry dts yes date/time after which the action can be performed

List Undoable Actions

GET /undo/

Get a list of undoable operations. Returns a list of all requests currently in the undo queue for a particular user.

Response body:

    "success": true,
    "queue": [ // Array of undo queue objects


POST /undo/now/:id

Undo (cancel) an operation that is in the queue. The operation is identified using its id as a path parameter.


    "success": true

Expedite all

POST /undo/expedite

Expedites all the undoables in the queue. All actions will be performed as soon as possible.

Request body:


    "success": true

Expedite Undoable

POST /undo/expedite/:id

Expedites one specific undoable action. This action will be performed next, possibly ahead of others in the queue.


    "success": true