About Action Chains

An action chain drives a series of actions in response to a lifecycle event from the user interface. Events are what start them, and there are many types of events, such as:

• vbEnter: triggered when a page starts and can be used to fetch data
• ojAction: triggered when a button component is clicked
• onValueChange: 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 using the Action Chain editor to assemble predefined (built-in) actions into a sequence that performs the required task. If you need an action that isn't available, you can either use the Code action to add your own block of code, or you can create a custom action if you think you might need it again.

Here's an example of an action chain that runs two action chains asynchronously, and then uses the result from each to create a combined result. Through input parameters, the action chain receives four numbers, as shown in the Properties pane. Using the Run in Parallel action, one asyn() method is used to call an action chain that returns the quotient of two numbers, and another asyn() method is used to call an action chain that returns the product of two numbers. The Run in Parallel action returns an array (runParaResult, in this example), with the first element containing the value from the first asyn() method and the second element containing the value from the second asyn() method. The sum of the values is then displayed using a Fire Notification action:

Description of the illustration jsac-action-chain-example-run-parallel.jpg

Here's the action chain's code:

      const runParaResult = await Promise.all([
        async () => {
        
          const callChainDivNum1ByNum2Result = await Actions.callChain(context, {
            chain: 'divNum1ByNum2',
            params: {
              num1: num1ToDiv_ip,
              num2: num2ToDiv_ip,
            },
          });
        
          return callChainDivNum1ByNum2Result;
        },
        async () => {

          const callChainMultipleNum1ByNum2Result = await Actions.callChain(context, {
            chain: 'multipleNum1ByNum2',
            params: {
              num1: num1ToMul_ip,
              num2: num2ToMul_ip,
            },
          });

          return callChainMultipleNum1ByNum2Result;
        },
      ].map(sequence => sequence()));

      await Actions.fireNotificationEvent(context, {
        message: `Sum of returned values: ${runParaResult[0] + runParaResult[1]}`,
        summary: `Sum`,
      });

When creating action chains, keep in mind that each action chain has a scope that depends on where it's defined: at the application, flow, page, or fragment level. An action chain defined at the application level can be called from any flow or page, but a page-level action chain can only be called from that page— however, the chain itself can access variables defined on the page, parent flow, or application. 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.

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