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
    ]
  }

Undo

POST /undo/now/:id

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

Response:

  {
    "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:

Response:

  {
    "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.

Response:

  {
    "success": true
  }