Skip to content


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 back-office 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.

The ampliFi API 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 Description Schema Example
id ampliFi ID (handle) of the undo object string "ajhut"
AFiUserId ampliFi ID of the current user string "qweaurl8kgtlv9pc"
userId Copy of AFiUserId string "qweaurl8kgtlv9pc"
name Name of the action to be performed string "a sample queued function"
secsUntilActionable Time until the action can be performed number 10
redoOnError Number of retries permitted in case of error number 5
payload Data required to perform this action object { //payload for action function }
isActionable true if this action is currently actionable boolean true or false
action Function to be called to perform this action function function (given)
onError Function to be called if an error occurs function function (given)
onUndo Function to notify the user if the action is cancelled function function (given)
onSuccess Function to notify the user if the action completed successfully function function (given)
dtsQueued Date/time item was placed in the queue dts "Mon Dec 18 2023 08:21:54 GMT-0500 (Eastern Standard Time)"

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 Description Schema Example Values
id ampliFi ID (handle) of the undo object string "ajhut"
isActionable true if the action can be performed immediately boolean false
dtsQueued Date/time the item was queued dts "Mon Dec 18 2023 08:21:54 GMT-0500 (Eastern Standard Time)"
dtsExpiry Date/time after which the action can be performed dts "Mon Dec 18 2023 08:21:54 GMT-0500 (Eastern Standard Time)"