Overview

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) { //some function }
onError	Function to be called if an error occurs	function	function (given) { //some function }
onUndo	Function to notify the user if the action is cancelled	function	function (given) { //some function }
onSuccess	Function to notify the user if the action completed successfully	function	function (given) { //some function }
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)"