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.
|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:
|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 a list of undoable operations. Returns a list of all requests currently in the undo queue for a particular user.
Undo (cancel) an operation that is in the queue. The operation is identified using its id as a path parameter.
Expedites all the undoables in the queue. All actions will be performed as soon as possible.
Expedites one specific undoable action. This action will be performed next, possibly ahead of others in the queue.