Work with Actions and Action Chains

The behavior of each component in your application is determined by an action chain, a sequence of actions started by an event listener when an event occurs in a page.

About Action Chains

An action chain determines what happens when, for example, you click a button on a page. To configure the button's behavior, you could define an ojAction event for the button, create an event listener that listens for that ojAction event to occur, and select the action chain that the event listener will start. When the button's ojAction event occurs, the event listener starts the action chain.

An action chain might be a short sequence of a few actions, but it could contain many actions as well as logic for determining what happens in the sequence. It might contain actions such as assigning data to a variable, sending data to a database, navigating to another page, even starting other action chains.

This image shows what an action chain that opens a URL might look like:
Description of designer-actionchain.png follows
Description of the illustration designer-actionchain.png

Much like variables, the scope of an action chain depends on where it's created. An action chain created in a page’s Action Chain editor can only be used in that page, and can only access variables defined in that page. An action chain that you create in the Action Chain editor for a flow can only be used within that flow. For action chains that you want to use in multiple pages of your application, such as one that navigates to the start page, you can create an action chain at the application level.

Create an Action Chain

You create action chains by assembling simple, individual actions into a sequence in the Action Chain editor. The Actions palette contains a list of built-in actions (grouped by type) that you can drag on to the canvas to create your sequence.

To create an action chain:

  1. Open your page's Actions tab.

    The Actions tab displays a list of the page’s action chains, or a message if no action chains are defined.
    Description of action-chain-editor-nochains.png follows
    Description of the illustration action-chain-editor-nochains.png

  2. Click + Action Chain.
  3. Enter a name for the action chain in the ID field and, optionally, a description. Click Create.

    The new action chain opens in the Diagram editor:
    Description of action-chain-editor-canvas-blank.png follows
    Description of the illustration action-chain-editor-canvas-blank.png

    The Action Chain editor contains the palette of built-in actions, a canvas, and a Properties pane. The Start icon in the canvas area indicates the starting point for your action chain; the Add icon ( Add icon ) is a placeholder where you add an action to the chain. The Properties pane shows the properties of what's selected on the canvas.

    If you prefer to wire up your action chain manually, you can use Code view to directly edit the action chain's source code. For supported syntax, see Actions and Action Chains in page model documentation.

  4. From the actions palette, drag an action and drop it on the Add icon ( Add icon ). Alternatively, click the Add icon ( Add icon ) in the chain and select an action in the pop-up menu.

    Description of action-chain-editor-popupmenu.png follows
    Description of the illustration action-chain-editor-popupmenu.png

    The new action is added to the chain and is selected by default. The Properties pane displays the properties that you can specify for the action. For example, here's what the editor looks like when you add the Assign Variables action in the Design view:
    Description of action-chain-editor-canvas.png follows
    Description of the illustration action-chain-editor-canvas.png

    The action is usually flagged with a warning icon when a required field isn't set (in this case, because a variable hasn't been assigned yet). Specify the action's properties as required in the Properties pane. For details specific to an action, see Built-in Actions.

  5. To create a fork in your action chain, drag the action from the palette and drop it on the Add icon next to the action where you want the chain to fork. The Add icon appears next to each action in the chain when you drag an action from the palette.
  6. Repeat step 4 (and optionally step 5) until your action chain is complete. The action chain is saved automatically.

    Description of action-chain-editor-finished.png follows
    Description of the illustration action-chain-editor-finished.png

    If you want to remove an action from the chain, select the action on the canvas, right-click, and select Delete ( Delete icon ). You can also click Delete in the properties pane's options menu.

    Tip:

    When your action chain includes a large number of actions, you can use search to quickly find what you're looking for. In the Search text box, enter any text—variable name, endpoint ID, or even an action ID from the console log. All actions that match the text you enter will be highlighted, along with navigation arrows that you can use to jump from one highlighted action to the next.

    Here's an example of using "etag" to find the expenseReportEtag variable:
    Description of action-chain-editor-canvas-search.png follows
    Description of the illustration action-chain-editor-canvas-search.png

    You can also click the Show Overview icon (Show Overview icon) to view a visual representation of the action chain's flow. In combination with search, the overview diagram can help you know where the highlighted action is within the overall flow. Toggle the Show/Hide Overview icon icon to show or hide the diagram as required.

You can open your action chain at any time from the Actions tab and edit it as necessary. When your action chain is complete, you can start it from a component, a lifecycle event, or from another action chain. You can also trigger it when a variable changes.

If you want to view usage details for your action chain (for example, to see which pages use the action chain), look under Usages in the action chain's Properties pane. Click a usage to readily navigate there. The event listener tied to the event that calls the action chain is also listed, as shown here:
Properties pane for an Action Chain

An action chain's source code is stored in its own JSON file. This helps to optimize performance by reducing the size of the artifact JSON and to reduce the potential for merge conflicts when multiple action chains for an app integrated with a Git repo are edited. To view an action chain's JSON file, click Source View. For action chains in applications, flows, and dynamic layouts, look in the artifact's chains folder. For action chains in pages, look in the pagename-page-chains folder under pages that's at the same level as the page JSON file:
Description of action-chains-json-source-view.png follows
Description of the illustration action-chains-json-source-view.png

If you create tests for your action chain, those will be stored in another JSON file, distinct from the action chain's file.

Note:

Action chains created with version 21.10 or later use separate JSON files by default. For action chains created in earlier versions, you have the option of moving the action chain's metadata from the artifact JSON to its own JSON file. See Migrate an Action Chain.

Built-in Actions

Visual Builder provides a set built-in actions that you use to create your action chain.


Description of action-chain-palette.png follows
Description of the illustration action-chain-palette.png

Each action performs a specific function and requires you to set different properties. For example, when you add the Call REST endpoint action to your action chain, you need to specify the endpoint and other details about the response to the Call REST endpoint action. Similarly, when you add the Navigate action to an action chain, you are required to select a page in your application that the action navigates to, as shown here:


Description of action-chain-simple-navigate.png follows
Description of the illustration action-chain-simple-navigate.png

Use this section to learn more about the steps particular to a built-in action.

Note:

Some built-in actions might be deprecated over time. To view actions deprecated in the latest release of Visual Builder, use the Show Deprecated option in the Actions palette's menu. The actions will show up in the actions palette, but won't be updated any more. The Show Deprecated option gives you time to move away from deprecated actions in your action chains.

Add an Assign Variables Action

You add an Assign Variables action to an action chain to map the source of some value to a variable. The variable can be used by other action chains or bound to a component.

For example, if your action chain sends a request to a GET endpoint, you can use the Assign Variables action to map the response to a page variable bound to a page component. Or, suppose you want to capture the ID of an item selected in a list. You could use a Selection event to start an action chain that assigns the selected item’s ID to a variable.

To add an Assign Variables action to an action chain:

  1. Open the Actions editor for the page.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Assign Variables from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the action to the chain.


    Description of action-chain-editor-assignvariable.png follows
    Description of the illustration action-chain-editor-assignvariable.png

    The Assign Variables action is badged with a warning icon when no variables have been assigned.

  4. Type a name for the action in the Id field in the properties pane.
  5. Click Assign in the properties pane to open the Assign Variables window to map the source of the value to a page variable.
  6. Drag the sources of the values in the Sources pane onto targets in the Targets pane. Click Save.

    Each target can only be mapped to one source, but you can use the action to assign multiple variables. For example, you might want to map a value from the Chain in the Sources pane, such as an input variable or the result of an action, to a Page variable or to the input of another action in the Target pane. When you select the variable in the Target pane, the expression editor in the dialog box displays the expression for the source.

    If you need to define the variable, use the + icon to open a dialog where you can define a variable for the artifact (action chain, page, flow, or application).


    Description of action-chain-editor-assignvariable-mapdialog.png follows
    Description of the illustration action-chain-editor-assignvariable-mapdialog.png

Add a Call Action Chain Action

You add a Call Action Chain action to an action chain to start a different action chain.

The action can call other action chains defined in the same page or in the application.

To add a Call Action Chain action:

  1. Open the Actions editor for the page.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Action Chain from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens in the editor when you add the action to the chain.


    Description of action-chain-editor-callactionchain.png follows
    Description of the illustration action-chain-editor-callactionchain.png
  4. Select an existing action chain from the drop-down list of available action chains, or click Create to create a new action chain.

    The dialog where you create the new action chain to call displays a drop-down list where you choose where to define the scope of the new action chain (Page, Flow, or Application). Depending on where you are creating the action chain, the drop-down list might have entries for action chains defined in the page, in the current flow, or in the application. If you are creating an action chain in a flow artifact, you can only select other action chains defined in the same flow artifact or in the application artifact, and you will not see an entry for Page action chains.


    Description of action-chain-editor-selectactionchain.png follows
    Description of the illustration action-chain-editor-selectactionchain.png
  5. Optional: If the action chain that is called requires input parameters, click Assign in the Input Parameter section of the properties pane to map the input parameter to a variable.

    You map variables to parameters by dragging the variable for the source value in the Sources pane onto the Parameter for the input parameter in the Target pane. If a suitable variable does not exist, use the + icon beside the relevant node (Action Chain, Page, and so on) to create a new variable. Click Save.


    Description of action-chain-editor-callactionchain-map.png follows
    Description of the illustration action-chain-editor-callactionchain-map.png

Add a Call Component Action

You add a Call Component action to an action chain to call a method on a component.

To add a Call Component action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Component from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the action to the chain.


    Description of action-chain-editor-callcomponentmethod.png follows
    Description of the illustration action-chain-editor-callcomponentmethod.png
  4. Enter a name for the action in the Id field in the properties pane.
  5. Enter the name of the component in the Component Selector text field.

    In the text field you enter the actual name of the component that you want to call, for example, $page.components.byId('myCard') or {{ document.getElementById('myCard') }}.

  6. Select or enter the Method Name and click Assign to map the parameters required by the method.

Add a Call Function Action

You add a Call Function action to an action chain to call a function defined for the current page, current flow, or the application. You create and edit module functions in the JavaScript editor.

To add a Call Function action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Function from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the action to the chain.

  4. Enter a name for the action in the Id field in the properties pane.
  5. Select an existing function from the drop-down list of available functions, or click Create to create a new function.

    You can select functions that are defined for the current page, the current flow, or for the application.


    Description of action-chain-call-modulefunction.png follows
    Description of the illustration action-chain-call-modulefunction.png
  6. Click Go to Module Function to go to the JavaScript editor where you write or modify code for the function.
  7. Specify any input parameters and return type for the function in the properties pane.

    You can click Assign to map variables to the parameters. If a suitable variable does not exist, use the + icon beside the relevant node (Action Chain, Page, and so on) to create a new variable.

Add a Navigate Action

The Actions palette contains a Navigation section that provides actions for navigating to a specific page in the application, the previous page, or an external URL.

When you add a Navigate action to an action chain to navigate to a specific page in your app, after you select the page to navigate to, you can map any input parameters defined for the page.

To add a navigation action to an action chain:

  1. Open the Actions editor for the page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag an action from the Navigation section of the palette into the action chain.

    The Navigation section contains Navigate, Navigate Back and Open URL actions.


    Description of action-chain-navigation-actions.png follows
    Description of the illustration action-chain-navigation-actions.png

    You can drag the action onto the Add icon ( Add icon ) in the action chain; typically this action will be the final action in the chain. The properties pane opens when you add the action to the action chain.

  4. Specify navigation details in the properties pane.
    • If you add the Navigate Back action, you don't need to specify any details, unless you want to optionally specify a key/value pair map of parameters to pass to the previous page.
    • If you add the Open URL action, provide the URL in the properties pane.
    • If you add the Navigate action, the following navigation types are available to you:
      • Page: Enables navigation to a sibling of the current page or a deeply nested page relative to the root of the application or the current page.
      • Flow in Parent Page: Enables navigation to a flow of the parent page.
      • Flow in Current Page: Enables navigation to a flow or page within the current page. This option shows only if the page includes a flow container component.
      Complete the following steps as it applies to your use case:
      1. Select an existing page from the drop-down list of available pages, or click the Create link next to Page to create a new page as the target for the Navigate action.

        The pages you can select can be one of the root (shell) pages of the application, another flow or page in the current flow, or a different flow of the parent page. One or more of these options might not be valid targets for your action chain. Here is an example of properties for navigation to a deeply nested page:

        Description of action-chain-editor-selecttarget.png follows
        Description of the illustration action-chain-editor-selecttarget.png
      2. If required, enter a name for the action in the Id field in the properties pane. You can edit the action’s properties in the properties pane when the action is selected on the canvas.
      3. If the page you select requires input parameters, click the Assign link next to Input Parameters to map a page variable to the action’s Input Parameter. Click Save.

        In the Assign Input Parameters dialog box, you map Sources to Targets by dragging the variable in the Sources pane onto the parameter in the Target pane. If a suitable variable does not exist, use the + icon beside the relevant node (Action Chain, Page, and so on) to create a new variable.

        You can click the parameter name to view the expression for the mapped variable.
        Description of action-chain-map-pageinputparameters.png follows
        Description of the illustration action-chain-map-pageinputparameters.png

Add a Call Variable Action

You add a Call Variable action to an action chain to call a method on an InstanceFactory variable defined for the current container (flow, page, or application). You can use this action to call any method on the current instance associated with the InstanceFactory variable, including asynchronous ones.

Note:

Because actions are by design synchronous, it will wait for the asynchronous call to resolve before proceeding to the next action in the chain.

Before you use a Call Variable action in an action chain, make sure an InstanceFactory type variable is already defined for the application. See Create a Custom Type From Code.

To add a Call Variable action to an action chain:

  1. Open the Actions editor for the application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Variable from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the action to the chain.

  4. Enter a name for the action in the Id field in the properties pane.
  5. From the Variables drop-down list, select an InstanceFactory type variable defined for the application.
  6. In the Method field, select the method you want to call. The available methods are based on the definition file imported for the type.
  7. Click Assign to open the Assign Parameters window, then map variables to the action's parameters by dragging the variable in the Sources pane onto the parameter in the Target pane. If a suitable variable does not exist, use the + icon to create a new variable.

    The method's return value will be part of the outcome passed to the subsequent chain.

Add a Call REST Action

When you add a Call REST action to an action chain, you might need to specify input parameters for the endpoint request or create variables for the endpoint response that you can bind to page components.

When you add the Call REST action to an action chain, the endpoint that you select will depend upon the functions that are available. Depending on the function, you might also need to create some variables to map to the action’s parameters, such as input parameters and the action’s results. For example, an endpoint might require an ID to identify a record. In this case, you will need to create a page variable that stores the ID, and that variable needs to be mapped to the action’s input parameter. If you did not create the variables before creating the action chain, you can create a variable during the process of creating the action chain; you can also edit the action chain after creating the variables you need.

You will use the Call REST endpoint action in action chains that perform typical functions such as creating, updating, and deleting records, and any time you want to display the details of a record in a page. You can use the Quick Starts to help you create the action chains and variables for these functions.

Type of Endpoint Typical Requirements
POST

When you call a POST endpoint, you will typically need:

  • Parameters: The page variable for the data needs to be mapped to the parameters of the payload of the POST call.

  • No input parameter is required.

GET

When you call a GET endpoint, you will typically need:

  • Input parameter: The ID of the record you want to retrieve should be passed as an input variable.

  • The payload of the GET call needs to be assigned to a variable using the Assign Variable action.

When you want to send a request to a GET endpoint to retrieve a collection, you will typically use a page variable of the type ServiceDataProvider.

DELETE

When you call a DELETE endpoint, you will typically need:

  • Input parameter: The ID of the record you want to delete should be passed as an input variable.

  • There is no payload when calling a DELETE endpoint.

PATCH

When you call a PATCH endpoint, you will typically need:

  • Input Parameter: The page variable storing the ID of the record you want to update should be mapped to the Input Parameter.

  • Parameters: The page variable for the updated data needs to be mapped to the parameters of the payload of the PATCH call.

To add a Call REST endpoint to an action chain:

  1. Open the Actions editor for the page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag Call REST from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the Call REST endpoint action to the action chain.


    Description of action-chain-editor-selectendpoint.png follows
    Description of the illustration action-chain-editor-selectendpoint.png
  4. Click Select beside the Endpoint property in the properties pane.

    The Select Endpoint window displays a list of the endpoints that are available in your application. Each business object and service usually exposes multiple endpoints. The endpoint that you select will depend upon the function of the action chain. The endpoint that you select will also determine the properties that you will need to specify for the action, for example, input parameters.


    Description of action-chain-editor-selectendpoint-dialog.png follows
    Description of the illustration action-chain-editor-selectendpoint-dialog.png
  5. Select an endpoint from the list. Click Select.
  6. Edit the action’s properties in the properties pane.

    The properties pane is displayed when the action is selected on the canvas.


    Description of action-chain-properties-callrest.png follows
    Description of the illustration action-chain-properties-callrest.png
  7. Optional: If the REST call requires input parameters, click Assign next to Input Parameters to map the variable for the input value to the action’s parameter. Click Save.

    You map variables to parameters in the Assign Input Parameters window by dragging the variable in the Sources pane onto the parameter in the Target pane. In some cases, you might need to make multiple mappings. To delete a line mapping a variable to a parameter, place your cursor on the line and then right-click to open a Delete option. You can select the parameter name to view the expression for the mapped variable.
    Description of action-chain-map-inputparameters.png follows
    Description of the illustration action-chain-map-inputparameters.png

    If a suitable variable does not exist, use the + icon beside the relevant node (Action Chain, Page, and so on) to create a new variable.

  8. Optional: If the REST call requires other parameters, click Assign in the Parameters section to open the window for mapping the variables to the action’s parameters. Click Save.

    If the structure and names of attributes match, they can be automapped. The mapping can also be done individually.

  9. Optional: Specify any other parameters that may be required for the action.
After adding the Call REST endpoint action, you can continue by adding more actions to the action chain, or by invoking the action chain from an event. If the REST call has a result, you might want to add a Fire Notification action, or add Assign Variables to the chain and map the result to a page variable.

Add a Fire Event Action

You add a Fire Event action to invoke a custom event that you have defined in your application.

A custom event can be defined in an application, flow or page, and can be used to perform some action, such as navigating to a page. A custom event can carry a payload that you define when you create the event. The Events editor displays a list of the custom events available in the context.

To add a Fire Event Action:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Fire Event from the Actions palette into the action chain.
  4. Type a name for the action in the Id field in the properties pane.
  5. Select an existing custom event from the drop-down list of available custom events, or click Create to create a new custom event.

    The drop-down list displays the custom events that are available in the current context.

  6. Click Assign to open the Mapper and define the event's payload.

    The event payload depends upon how the custom event is defined. You can use the Mapper to map the payload to a source, such as a page variable, or define a specific value or expression.

    If you need to define the variable, use the + icon to open a dialog where you can define a variable for the artifact (action chain, page, flow, or application).

Add a Fire Notification Action

You add Fire Notification actions to display notification messages in the browser window.

You add a Fire Notification action for each message that you want to add to the action chain. When you add the action, you select the type of result that will cause the notification to fire by selecting a notification type. For example, if an error occurs when performing an action in the chain, the notification will appear if you select error as the notification type. If you also want a notification to appear when the action succeeds, you will need to add another Fire Notification action and set the notification type to confirmation.

To add a Fire Notification action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Fire Notification from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The properties pane opens when you add the action to the chain.


    Description of action-chain-editor-firenotification.png follows
    Description of the illustration action-chain-editor-firenotification.png
  4. Enter a name for the action in the Id field in the properties pane.
  5. Enter a summary of the notification in the Summary field.
  6. Enter the message you want to display in the Message field.

    The message can be a static string (The name was updated.) or can contain variables ({{ 'Could not create new Contacts: status ' + $chain.results.createContacts.payload.status }}).

  7. Select a Notification Type to specify the type of result that will fire the notification, and a Display Mode to specify how the notification is displayed.
  8. Select the Target to specify where you want the event to be fired. Choose current to have the event fire where it is executed and then all the way up the hierarchy. Choose leaf (or leave the setting undefined) to have the event fire at the bottom of the hierarchy.

Add a Logout Action

You can add the Logout action to any page component to launch the logout mechanism that enables your users to sign out of an application.

To add a logout action to an action chain:
  1. Open the Actions editor for the page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag the Logout action from the Actions palette into the action chain. You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain.
    The Properties pane opens when you add the action to the chain:

  4. If you're using an external identity provider, enter the provider's logout endpoint URL in the Logout URL field, something like https:***/oam/server/logout?end_url=https://****/oamwebsso/logout-success.jsp.

    If you're using IDCS for user authentication, you don't need to specify the logout URL. In this case, the URL defined by the default Security Provider configuration is used. After the user is logged out, the application continues to the default page of the application.

Add a Scan Barcode Action

You can add the Scan Barcode action when you want your application to decode information such as URLs, Wi-Fi connections, and contact details from QR codes and barcodes.

Note:

The Scan Barcode action relies on browser APIs and is supported only on Chrome for Visual Builder apps.

To add a scan barcode action to an action chain:

  1. Open the Actions editor for the page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag Scan Barcode from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The Properties pane opens when you add the action to the chain.



  4. Specify the action's properties in the Properties pane:
    1. In the Image field, enter an image object (either a CanvasImageSource, Blob, ImageData, or an <img> element) to decode.

      Note:

      If you're using the Take Photo action or the camera component to pass a Blob to the Scan Barcode action, you might run into the Failed to execute 'detect' on 'BarcodeDetector error. To get around this error, convert the Blob to an ImageBitmap before passing it to the Scan Barcode action. For example:
      1. Add a function to do the image conversion, something like:
          // Convert Blob to ImageBitmap
          //
         PageModule.prototype.createImageBitmap = function(fileBlob) {
            return window.createImageBitmap(fileBlob);
          };
      2. Add a Call Function action to the action chain, similar to:

      3. Pass the converted ImageBitmap as the Image parameter for the Scan Barcode action, for example:
        [[ $chain.results.callFunctionCreateImageBitmap ]]
    2. Optional: In the Formats field, select the barcode formats you want the browser to search for.

      Barcode formats unlock a variety of use cases. QR codes can be used for online payments, web navigation, or social media connections, aztec codes can be used to scan boarding passes, and shopping apps can use EAN or UPC barcodes to compare prices of physical items.

      If Formats is not specified, the browser will search all supported formats, so limiting the search to a particular subset of supported formats may provide better performance.

    One option when using the Scan Barcode action is to use document.querySelector to get the image, as shown here where the first image with the ID BarcodeImage will be returned:
    Description of action-chain-call-scanbarcode-example.png follows
    Description of the illustration action-chain-call-scanbarcode-example.png

Test Action Chains

Visual Builder provides an editor to help quickly generate unit tests for your action chains by generating suggestions of outcomes in the action chain to validate.

Using this editor, you can apply test-driven development as an approach in creating action chains. The editor detects what information needs to be provided at runtime to perform the actions in the action chain. This information includes values for variables and constants used by the action chain, and actions like Call REST endpoint actions, the results of which need to be mocked when running a test. Once the necessary context is provided, the editor generates suggestions for expected outcomes that you can add to the test, or you can add your own expected outcomes (expectations).

You access this editor from the Tests tab in the Actions editor of an individual action chain. Once in the editor, you can create one or more tests for the associated action chain. For each test, you define context, mock actions, and expected outcomes. A context refers to a variable that the action chain uses. If, for example, you have an action chain that uses a Call Function that takes a subtotal variable as input and returns the total after tax, add a context entry that includes the subtotal variable and a sample value for the variable.

Mock actions are needed for Call REST endpoint actions and other actions in the action chain. For each mock action, you specify a possible outcome for the action and a result. If, for example, your action chain includes a Call REST endpoint action that fetches product information, you need to specify a mock action that has a success outcome and includes a sample result of product information. Right-click the action for which you need to define a mock action, and choose Mock Action from the context menu that appears to add a mock action. Finally, you specify the expected outcomes for the test. Visual Builder generates a set of suggestions for expected outcomes that you can add to the test. You can add one or more of these expected outcomes to the test, and edit the expected outcome.

Once you have defined the tests, you can run them individually or simultaneously using the appropriate button that the editor provides (Run or Run All). You can also run these tests using the vb-test grunt task, if you export your visual application. See Test Action Chains Using the vb-test Grunt Task.

The following image shows the Tests editor where three tests have been defined for an action chain that fetches product information. Two of these tests have run (Failure Path and Success Path), and one has not (Test Three). The red icon beside the Failure Path test indicates that it failed; the reason for the failure is also marked red in the expectation for the fireNotification message, where the test author set the expected outcome to Action Failed but the actual outcome was undefined. The green icon beside the Success Path test indicates that the test succeeded. No visual indicator appears beside Test Three because it has not yet been executed.Description of test-overview-threetests.png follows
Description of the illustration test-overview-threetests.png

The percent value for Coverage indicates the level of test coverage for the actions in the action chain. If you create tests that include all actions in the action chain, and all expected outcomes for the actions, the percent value for Coverage will be 100%. In the preceding image, the test author removed a series of entries from the Expectations list for the Failure Path test, thereby reducing the Coverage percent value for the action chain to 67%. For the action chain in the image, you can increase the value for Coverage by adding entries that appear under the Suggestions list to the Expectation list.

The first time that you access the Tests editor, click the + Test button to create a test. The test name defaults to Test 1. Specify an alternative test name, if you want.

Once you create a test, the Tests editor enables the following UI controls that assist you in developing and running a test:
  • A pane on the right of the Tests editor appears for you to add context, mocks, and expectations for the test.
  • Run and Delete buttons that you use to run and delete the test.

The source code for all your tests is stored in a separate JSON file (actionchain-tests.json), one for each action chain. Click JSON in the left pane to view the file's contents. You can also find this file under the artifact's chains folder in Source View.

An aggregated view of all the tests that you've defined for web and mobile apps in your visual application can be displayed by clicking Tests in the status bar of your browser. This displays a view of all action chain tests per application, in addition to a visual indicator that gives the status of the test (Pass/Fail/Not Run). It also provides a button (Run All) that runs all tests in the visual application simultaneously.

Description of test-action-chain-aggregate.png follows
Description of the illustration test-action-chain-aggregate.png

Test Action Chains Using the vb-test Grunt Task

Visual Builder’s grunt-vb-build NPM package includes a vb-test Grunt task that you can use to run the action chain tests in your visual application on your computer.

To use the vb-test Grunt task, you must set up your computer to build the visual application by installing Node.js and its package manage (npm). See Build Your Application Locally. Once you have installed the necessary tools, you need to save the sources for the visual application to your computer. You can get the sources of your visual application in one of the following ways:

  • Cloning the Git repository containing the sources
  • Exporting the visual application from Visual Builder and extracting it to your local system

To test action chains using the vb-test Grunt task:

  1. In the command-line interface, navigate to the folder on your local system containing the package.json and Gruntfile.js files.
  2. Enter npm install to retrieve the node dependencies required to build the application.

    The install command retrieves the grunt-vb-build npm package defined in package.json.

  3. Enter the task names in the command-line interface to process your application sources, and then run the suite of tests that you defined in Visual Builder.

    The following example shows how you execute these tasks, along with some of the parameters that they support:

    # First build application sources. This creates a build/processed directory with the built application assets.
    ./node_modules/.bin/grunt vb-process-local
    
    # Run the suite of action chain tests that you defined using one of the following options: 
    ## Headless mode:
    grunt vb-test 
    ## Test in the Chrome browser and set a timeout value:
    grunt vb-test --karma-browser=Chrome --mocha-timeout=60000
    
    The command-line options include the following:
    • karma-browser

      By default the tests run in headless Chrome, but you can pass Chrome to use the UI (window) mode instead. You can also use Firefox, if you prefer.

      Example to run tests in Chrome UI:

      grunt vb-clean vb-process-local vb-test--karma-browser=Chrome

    • karma-debug

      Runs tests in Chrome UI mode. Suspends execution until you click the DEBUG button, at which point you can debug the app tests using Chrome DevTools. The Default value is false.

      Example to run tests in Chrome UI and debug mode:

      grunt vb-clean vb-process-local vb-test --karma-browser=Chrome --karma-debug

    • karma-log-level

      Sets the karma logging level. The default level is INFO, though you can change this to DEBUG, WARN, ERROR, or DISABLE.

      Example to run tests in Chrome UI with increased verbosity:

      grunt vb-clean vb-process-local vb-test --karma-browser=Chrome --karma-log-level=DEBUG

    • mocha-timeout

      Sets the timeout for Mocha tests (in milliseconds).

      Example to run tests in Chrome UI with a timeout for Mocha tests:

      grunt vb-test --karma-browser=Chrome --mocha-timeout=60000

    For more information on the supported command-line options, see vb-test.

  4. Check test results and code coverage reports in the build/tests/results directory.

Start an Action Chain From a Component

When you add a component to a page, you'll need to create a component event and component event listener if you want it to trigger some behavior, for example, to open a URL. The Quick Start option in the component's Properties pane creates these for you.

There are various predefined events that you can apply to a component, and the events available are usually determined by the component. For example, the ojAction event is triggered when a button is clicked, so you would typically apply it to a button component (you couldn't apply it to a text field component). Each button will have a unique event and an event listener listening for the button's ojAction event, and the listener would start an action chain (or multiple action chains) when the event occurs. Each component event will usually have a corresponding component event listener.

Note:

You can add an event to a component only from the component's Properties pane. You can't create one in the Events tab of pages.

To start an action with a component:

  1. Select the component in a page.

    Typically, you assign events to elements such as buttons, menus, and fields in form components. You can select the component on the canvas, in the Structure view, or in Code view.



  2. In the component's Events tab in the Properties pane, click + New Event. You can choose the Quick Start option or you can create a custom event. The Quick Start uses the suggested event for the component, but you could choose the custom event option to use a different event.

    When you add the new event using the Quick Start, an action chain is created for you and the Action Chain editor opens automatically. When you add the new event using the custom option, you'll need to select an event.

  3. Select the event you want to use to trigger an action chain. Click Select.
  4. Select the action chain you want the event to trigger and click Select Action Chain. Alternatively, click New Action Chain to create a new action chain.

The Events tab in the Properties pane shows the properties of the component event. You can edit the properties, for example, to assign input parameters that you might want to use in the action chain.
Description of event-listener-component-edit.png follows
Description of the illustration event-listener-component-edit.png

If you used the Quick Start option to add an event, a component event listener is created for the new event, and the listener is mapped to the action chain it created for you. If you open the Event Listeners tab, you'll see it listed under Component Event Listeners, and the action chain that it will trigger.
Description of event-listener-component-qs.png follows
Description of the illustration event-listener-component-qs.png

Start an Action Chain When a Variable Changes

You can start an action chain when the value stored in a variable changes by adding an onValueChanged event to the variable.

When you use an onValueChanged event to trigger an action chain, the trigger has the payload of the variable's old and new values. For example, let's say you changed the name property of an Employee and then reset the Employee; the framework will send an event that the Employee changed, and as part of the payload indicate that the name has changed.

To start an action chain when the value of a variable changes:

  1. Open the Variables tab of an artifact.
  2. Select the variable in the list, then open the Events tab in the Properties pane.
  3. Click + Event Listener in the Events tab.
  4. Select an action chain from the list. Click Select.

    When you add the event to the variable, a variable event listener that listens for the onValueChanged event on the variable is automatically created. The variable's Events tab in the Properties pane displays the action chain the event listener will trigger; you can change or remove the action chain, assign input parameters, and add more action chains.
    Description of event-listener-variable.png follows
    Description of the illustration event-listener-variable.png

    Note:

    Variable events and event listeners are not listed in an artifact's Events or Event Listeners tabs.

Start an Action Chain From a Lifecycle Event

Lifecycle events are predefined events that occur during a page's lifecycle. You can start action chains when these events occur by creating event listeners for them. For example, if you want to initialize some component variables when the page opens, you can create an event listener in your artifact that listens for the vbEnter event. You could then set the event listener to trigger an action chain that assigns values to the component's variables.

This table describes the lifecycle events you can use.
Lifecycle Event Description
vbBeforeEnter Triggered before navigating to a page. Commonly used if a user does not have permission to this page or to redirect to another page.
vbEnter Triggered after page-scoped variables have been initialized. Commonly used to trigger data fetches.
vbBeforeExit Triggered before navigating away from a page. Commonly used if a user should not be allowed to leave a page before saving changes.
vbExit Triggered when navigating away from the page. Commonly used to perform cleanup.
vbAfterNavigate Triggered after navigation to the page is complete.
vbResourceChanged Triggered when an application has been updated. Commonly used to notify the user that they need to refresh to view the updated application.
vbDataProviderNotification Triggered when a Data Provider's implicit fetch fails with an error.

To start an action from a lifecycle event:

  1. Open the Event Listeners tab for the page containing the event that you want to trigger the action chain.
  2. Click + Event Listener.
  3. In the Create Event Listener wizard, expand the Lifecycle Events category and select the event you want to trigger an action chain. Click Next.
  4. Select the action chain that you want to trigger. You can select any action chain that is scoped for the artifact. For example, if you are creating an event for a flow artifact, you can only call action chains defined in the flow or in the application.

    If you want to create a new action chain now, you can click Add Action Chain iconand enter an ID for the new action chain, which you can edit later in the editor. Click Finish.



After you create an event listener, you can click Add Action Chain for the lifecycle event if you want it to start additional action chains.

Start an Action Chain From an Action Chain

You can start an action from within another action chain using a custom event, which is triggered by the Fire Event action in an action chain. Typically, you would use a custom event when you want to trigger a notification, like displaying a pop-up window with a message, or perhaps when you want to transform some data. After creating a custom event, you need to create an event listener for it to start the action chain.

Each custom event has a Behavior property, which you can use to set whether action chains run serially or in parallel. The default behavior is "Notify", which allows the action chains to run in parallel. For more about setting an event's Behavior property, see Choose How Custom Events Call Event Listeners.

To start an action chain with a custom event:

  1. Open the Actions tab for a page, flow, or application.
  2. Select the action chain you want to edit. The action chain opens in the Action Chain editor. If you want to create a new action chain, click + Action Chain.
  3. In the Action chain editor, drag the Fire Event action from the palette and drop it in the action chain where you want the event to occur.
  4. In the Fire Event action's Properties pane, specify the Event Name.

    If you are using the Fire Event action to trigger a new custom event, click Create, enter an Event ID, and specify the event's scope. If you want to trigger a custom event that already exists, you can select it in the drop-down list.
    Description of fire-event.png follows
    Description of the illustration fire-event.png

    After creating or selecting the event, you can click Go to Custom Event in the Properties pane if you want to edit the event's Behavior or Payload properties in the Events editor.

  5. Open the Event Listeners tab and click + Event Listener to open the Create Event Listener wizard
  6. Select the custom event you added to your action chain. Click Next.
  7. Select the action chain you want the event to trigger. Click Finish.

Migrate an Action Chain

You can migrate action chains that were created in version 21.07 or earlier to move the action chain's source from the artifact JSON to its own JSON file. Migrating action chain content to separate files reduces the potential for merge conflicts when multiple action chains for an app integrated with a Git repo are edited. It also provides performance gains by reducing the size of the artifact JSON.

Before you migrate action chains, make sure you back up your application by exporting it, making a copy, or pushing any pending changes to Git. If the app contains tests, run them before migration so you have a baseline to compare later.

To move an action chain's source to a separate JSON file:

  1. Open the application with the action chains you want to migrate.
  2. Click the Actions tab for a page, flow, or application, then select Migrate from a particular action chain's menu.


    You can also open the action chain in the editor, then select Migrate in the action chain's Properties pane menu.

  3. In the Migrate Action Chain dialog, select an option to migrate the current action chain alone, migrate all action chains in the current artifact, or migrate all action chains in the application. Click Migrate.

When migration is complete, each action chain's source shows up in separate JSON files, which you can locate in Source View. For action chains in applications, flows, and dynamic layouts, look for the JSON files in the artifact's chains folder. For action chains in pages, look in the pagename-page-chains folder. For example, when you migrate action chains for the main-start page, you'll find the JSON files in the main-start-page-chains folder under pages that's at the same level as the page JSON file. If your action chain included tests, a separate file is created for the test content.
Description of action-chains-json-source-view.png follows
Description of the illustration action-chains-json-source-view.png

Click a JSON file to inspect an action chain's source in Code view. You might also want to run your action chain's tests right after migration to make sure everything's working as expected.