Callback is a multi-purpose step type used to manage asynchronous background execution in Foundation. The detailed use of the step type is covered in the following sections.
It is useful, before looking at the detail, to understand the different modes of operation of the step type.
1. Create anchor
Anchor creation registers a step to which callbacks should be made. It is run by the foreground process.
Anchor creation is identified by a callbackAction of "create".
After anchor creation, the next.create flow is followed.
The anchor step can also have next flows to respond to callbacks - see section 3.
2. Dispatch callback
Callbacks are dispatched from the background process. They involve executing the anchor step from the background process.
A dispatch has a callback action of "start", "progress", "complete", "cancel" or "error".
The update may send a response.
The state of the dispatch will be set to the state of the callback. In the normal case, this would be based on the callback action (i.e. start, progress, complete, cancel or error), but could be a different state.
3. Handle callback
When the anchor step receives a callback update, it is processed by the anchor step. A callback is identified by having a data parameter object with "type": "CALLBACK" and a callbackAction of "callback" (or omitted).
This checks that the status in the callback is one of the permitted callback statuses (start, progress, complete, cancel or error). It also checks that the current callback is active, has not timed out, and is not an orphan
If the status has changed, it uses resume mode to continue the anchor processing.
After process resumption has finished (if applicable), it will set the state to "noop" (to indicate that the anchor should do nothing with the response) and return the status of the callback to the caller.
4. Resume
When the anchor is called back to change the status, or detects a timeout or inactive parent condition, it needs to follow the appropriate next steps. However, the results of those steps should not be revealed to the caller.
To achieve this, the anchor state calls itself recursively using a callback data area with a callbackAction of "resume". This simply branches according to the status, and runs the start, progress, complete, timeout, orphan or error branch.
5. Query
This is a call made in the foreground using the callback action "query" to determine the current status and response of the callback.
This involves an execution of the anchor step (see section 7). This will return the current status and response. The state on the query will be set to the status of the callback.
6. Await
This is call made in the foreground, using the callbackAction "await". The execution is blocked until the callback reaches an inactive state, such as complete, timeout or cancel.
Internally, this executes the anchor step to get the callback (see section 7). The state is set to the status of the callback.
7. Handle query
This is a call to the anchor step made internally by the "query" and "await" actions, using the action "getCallback".
If the callback is active, the anchor checks for timeouts and orphan conditions. If these are detected, it calls itself with the "resume" callback action to respond to these status changes.
After process resumption has finished (if applicable), it will set the state to "noop" (to indicate that the anchor should do nothing with the response) and return the status of the callback to the caller plus the response.
8. Check status
This is a call to the anchor step made internally by the anchor step of a child process. It uses the action "checkStatus".
This is similar to the anchor status query, except that:
- The returned status is translated to "active" or "inactive".
- No response data is returned.
9. Enforce
This is a scheduled call to the anchor step that enforces timeout conditions and other maintenance. It is invoked with a callback action of "enforce".
It checks all callbacks associated with the node, and if any are active and should be timed out, sets the status to timeout and uses the "resume" callback action to continue processing.
It checks all inactive callbacks without the retain indicator and if any have been inactive for more than an hour deletes the callback information and any associated saved responses.
It sets the state of the anchor to "enforce", which allows additional activities to be scheduled after cleanup.
Summary of modes
| Mode | Defined in | Called by | Actions | State | Response |
| Create anchor | Foreground | Foreground | anchor | create | status |
| Dispatch callback | Background | Background | start, progress, complete, cancel, error | notFound, start, progress, complete, error, timeout, cancel, orphan | status |
| Handle callback | Foreground | Background | callback | noop | status |
| Resume | Foreground | either | resume | notFound, start, progress, complete, error, timeout, orphan | full |
| Query | Foreground | Foreground | query | any | full |
| Await | Foreground | Foreground | await | any inactive | full |
| Handle query | Foreground | Foreground | handleQuery | noop | full |
| Check status | Parent | Child | checkStatus | noop | active/inactive status |
| Enforce | Foreground | Schedule | enforce | enforce | none |
The callback action is generally read from config.callbackAction.
The callback action will be read from the callbackAction of the "data" parameter, only when the following are all true:
- config.callbackAction is "anchor" or omitted.
- The data parameter contains an object with "type": "CALLBACK".
- The node in the data.callback token matches the context node.
If these conditions are not met, the data parameter is ignored.
If not ignred, the configAction within the dara parameter must be one of "callback", "resume", "getCallback", "checkStatus" or "schedule".