What is an Action Chain?

An action chain drives a series of actions in response to an event from the user interface. It can be short, like an action that makes a REST call, followed by another that takes the result of that call and stores it in a variable. An action can contain both actions as well as logic that determines what happens in the sequence, such as an action that calls a common function, followed by an if action that conditionally evaluates an expression and provides alternate paths based on the function call's result.

Action chains are always triggered by events. There are many types of events, such as the vbEnter lifecycle event, which occurs when a page starts and can be used to fetch data; the ojAction event that occurs when a button component is clicked; and the onValueChange event that's triggered when the value stored in a variable changes. No matter the type of event, every action chain must be bound to an event listener to be able to run it. Sometimes the event listener is created automatically, but sometimes you must create it explicitly. For example, if you accept the event that VB Studio suggests (say, the onValue event suggested for an Input Text component), the event listener is created for you, which will trigger an action chain when the component's value changes.

Creating an action chain involves assembling predefined (built-in) actions in the Action Chains editor, or using JSON code to create your own. Here's an example of an action chain that uses several built-in actions to open a URL:

Description of the illustration action-chain.png

While actions within a particular chain run serially, you can run multiple action chains concurrently by configuring the event listener to start multiple chains.

When creating action chains, keep in mind that each action chain has a scope that depends on where it's defined: at the App UI, flow, page, or fragment level. An action chain defined at the App UI level can be called from any flow or page, but a page-level action chain can only be called from that page—though the chain itself can access variables defined on the page, parent flow, or App UI. The same goes for flow-level action chains. A fragment-level or layout-level action chain can only be called from that fragment or layout, and the chain can only refer to variables defined in that fragment or layout.

An action chain also maintains its own context, which is accessible through an implicit object called $chain. Actions may export new state to that context, but it is only available to future actions along that action chain.