Work with Actions and Action Chains

You create action chains to define the behavior of components in a page.

About Action Chains

An action chain is a sequence of actions that you create to define the behavior of components.

Action chains are triggered by events such as click, onValueChanged and focus that you add to components and page events. They have a scope property that determines where they can be used. The action chains that you create in a page’s Actions editor can only be used within the context of the page and cannot be used in other pages. Action chains that you create in the Actions editor for a flow can only be used within that flow. See Add Events to Components and Start an Action Chain with an Event.


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

For action chains that you might want to use in multiple pages of your application, such as one that navigates to the start page, you can create an action chain that is application-scoped.

You create action chains by assembling simple, individual actions into a sequence in the Actions editor. The Actions editor contains a palette of built-in actions that you drag onto the canvas where you create your sequence. After you add an action to the sequence you usually need to provide details required by the action. 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 to Page action to an action chain, you are required to select a page in your application that the action navigates to.


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

The built-in actions are grouped in the palette by type. See Actions for a list of the built-in actions.

Create an Action Chain

You build action chains by dragging actions from the palette onto the canvas in the Action Chain editor.

To create an action chain:
  1. Open the Actions editor of your page.

    The Actions editor 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. Click Create.

    The new action chain opens in the editor. The Action Chain editor contains the palette of built-in actions, a canvas and a property editor. The Start icon indicates the entry point of your action chain and the Add icon ( Add icon ) is a placeholder indicating where you can add an action to the chain. The property editor displays the properties of the action that is selected on the canvas.



  4. Drag an action from the palette and place it on the Add icon ( Add icon ) in the chain.

    Alternatively, you can click the Add icon ( Add icon ) in the chain and select an action in the popup menu of actions.


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

    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.


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

    The new action is added to the chain and is selected by default. The property editor displays the properties that you can specify for the action. The properties depend upon the type of action.

  5. Specify the properties of the action in the property editor.
  6. Repeat steps 5 and 6 until your action chain is complete. The action chain is saved automatically.

    You can open your action chains at any time from the Actions editor and edit them as necessary.

    Tip:

    To remove an action from the chain, select the action on the canvas and click Delete ( Delete icon ) in the property editor.

When your action chain is complete you can start the action chain from an event in the page.


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

Start an Action Chain with an Event

You can start an action chain by defining an event listener that listens for a specific event, and when the event occurs the event listener can start one or more action chains. The types of events that are available depend on the type of artifact.

You select the type of event and the action chain in the Events editor of an artifact, such as a page. For example, you can use a page event, such as entering a page, to start an action chain. To start the action chain you would open the Events editor for the page to define an event listener, and then select the action chain that the event listener should start. To define the event listener, you select the event that the event listener listens for. This might be a default page event, like vbEnter, but it can also be a component event that you added to a component, like ojAction, which is usually applied to a button component. When designing your page you can use a Quick Start to assign events to components. For the steps, see Add Events to Components.

When creating an event listener you also need to select the action chain that should be started. You can create a new action chain or select one from the list of action chains that are already defined. The action chains that can be started from the event will depend on the scope of the action chain.

To add an event listener to start an action chain:

  1. Open the Events editor for the page containing the event that you want to trigger the action chain.

    The Events editor displays a list of all event listeners defined for the page, including details about where events are fired and the components that are firing them. The list will contain some default events as well as any events that you have defined, such as component events.



  2. Click + Event Listener in the editor.

    The Select Event window displays a list of event types that the listener can listen for.


    Description of page-designer-events-select.png follows
    Description of the illustration page-designer-events-select.png
  3. Select an event type from the list. Click Select.
  4. Select the action chain that will be started by the event listener.

    You can select any action chain that is scoped for the artifact. The window lists all action chains that can be started in the current context, grouped by scope. 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.



  5. Click Select.
After you create an event listener, you can click Add Action Chain if you want it to start additional 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 property editor 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 property editor.
  5. Click Assign in the property editor 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.


    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 property editor 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. Click Select Action Chain in the property editor.

    The Select Action Chain window displays a list of available action chains. Depending on where you are creating the action chain, the window might have tabs for action chains defined in the page, in the current flow and 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 a tab for Page action chains. You can use the Filter text field to filter the action chains in the list.


    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 property editor to map the input parameter to a variable.

    The action in the action chain is badged with a warning icon when an input parameter is required but has not been assigned.

    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. 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 Method Action

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

To add a Call Component Method 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 Method 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 property editor 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. Type a name for the action in the Id field in the property editor.
  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')

  6. Enter the Method Name and map the parameters required by the method.

Add a Call Module Function Action

You add a Call Module 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 Functions editor.

To add a Call Module 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 Module 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 property editor opens when you add the action to the chain.


    Description of action-chain-call-modulefunction.png follows
    Description of the illustration action-chain-call-modulefunction.png
  4. Type a name for the action in the Id field in the property editor.
  5. Click Select Module Function to open a window to select the functions available.
  6. Select the function in the Select Module Function window. Click Select.
    You can select functions that are defined for the current page, the current flow or for the application.
  7. Specify any input parameters and return type for the function in the property editor.
    You can click Assign to map variables to the parameters.

Add a Call REST Endpoint Action

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

When you add the Call REST Endpoint 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. If you did not create the variables before creating the action chain, you can edit the action chain after creating the variables you need.

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.

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 the following:

  • 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 the following:

  • 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 the following:

  • 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 the following:

  • 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 Endpoint 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 property editor 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

    The Call Rest Endpoint action is badged with a warning icon when no endpoint has been selected.

  4. Click Select Endpoint in the property editor.

    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 property editor.

    The property editor 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 in the property editor to open the window to map the variable for the input value to the action’s parameter. Click Save.

    You map variables to parameters in the Call REST Endpoint 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, you can create the variable in the Variables editor and edit the action later.

  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 Custom Event Action

You add a Fire Custom 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 Custom Events tab in the Events editor displays a list of the custom events available in the context.

To add a Fire Custom 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 Custom Event from the Actions palette into the action chain.
  4. Type a name for the action in the Id field in the property editor.
  5. Select the Custom Event in the Event Name drop-down list.

    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.

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 property editor 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. Type a name for the action in the Id field in the property editor.
  5. Type the message to display in the Message field.

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

  6. 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.

Add a Navigation Action

The Actions palette contains a Navigation section that provides actions for navigating to the previous page, a specific page in the application 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 target page you can specify an input parameter to specify the id of a record.

To add a navigation action to an action chain:

  1. Open the Actions editor for 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 Navigate to 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, and typically this action will be the final action in the chain. The property editor opens when you add the Navigate to Page action to the action chain.

  4. Specify the details of the page or URL in the property editor, if required. If you add the Navigate Back action you do not need to specify any details.. If you add theNavigate to URL action you need to provide the URL in the property editor. If you add the Navigate action you need to perform the following steps.
    1. Click Select Target in the property editor.
    2. Select the context of the target in the Select Target window.

      The targets you can select will depend upon the context of your action chain. The target for a Navigate action can be one of the root (shell) pages of the application, another page in the current flow, or a different flow that is defined in the current page. One or more of these options might not be valid targets for your action chain. After you choose the context of your target you can choose from the available targets in that context.

      Description of action-chain-editor-selecttarget-db.png follows
      Description of the illustration action-chain-editor-selecttarget-db.png
    3. Select a page in the list. Click Select.

      If the page you select requires an input variable you will need to map a page variable to the action’s Input Parameter.

    4. Type a name for the action in the Id field in the property editor.

      When the action is selected on the canvas, you edit the action’s properties in the property editor.


      Description of action-chain-editor-navtopage.png follows
      Description of the illustration action-chain-editor-navtopage.png
    5. Optional: If the page requires input parameters, click Assign in the Input Parameters section to open a window to map the variable for the input value to the action’s parameter. Click Save.

      In the window, you map Sources to Targets by dragging the variable in the Sources pane onto the parameter in the Target pane. 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

      If a suitable variable does not exist, you can create the variable in the Variables editor and edit the action later.

Test Action Chains

Visual Builder provides an editor to help quickly generate unit tests for your action chains by generating suggestions for you 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 module 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 outcome(s) 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 test(s), you can run them individually or simultaneously using the appropriate button that the editor provides (Run or Run All).

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 (Success Path and Failure Path), and one has not (Test Three). The red icon beside the Failure Path test indicates that it failed, as does the red border around the expectation for the fireNotification message where the test author set the expected outcome to Success! but the actual outcome was Bad Request. 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.

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 following 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 83%. 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.

Description of test-overview-threetests.png follows
Description of the illustration test-overview-threetests.png

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 where you can add context, mocks, and expectations for the test that you run.
  • Run and Delete buttons that you use to run and delete the test.

An aggregated view of all tests that you have defined for the mobile and web applications 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