Action basics

Action is a piece of business logic implemented in your application. You can use it to load data from data sources, send data back, make API calls, navigate to a page, generate PDF documents, or process any type of data with SQL, JavaScript, or Python.

Within any action, you have the ability to include multiple Action steps. These steps encompass predefined logic and can take various forms, such as SQL queries, custom JavaScript code, HTTP requests, conditions, and navigation, etc. By combining these steps together, you can construct functional workflows that enable you to merge requests from different data sources, validate input data, or trigger data reloads based on specific conditions. This flexibility allows you to create powerful and adaptable processes to meet your specific needs.

Creating an action

Open the Actions panel from the bottom of the builder area. Choose whether you need a global or a page-specific action, then click the + button on the right of the Actions list.

Select the data source first, then based on it, you will get a list of all the available action types. Select the necessary action type. You can also create complex multi-step actions. All the steps will be executed sequentially as you ordered them.

By default, if a step fails, the entire action will also fail. However, you can change this behavior by enabling a setting called Allow next step execution when this step has failed. When this setting is enabled, the next step will still run even if the current step fails. The {{data}} variable that would have been passed to the next step will be empty (null), and an error message will be stored in a variable called {{error}} to indicate the nature of the failure.

Another approach is to utilize a Condition step, which allows you to define different paths of execution based on specific conditions.

Action step variables

In any action step within the tool, you can access app variables like {{ui.component.value}} or {{app.env}}. Moreover, there are several built-in variables that are available in every action step:

1. {{data}} - the result of the previous step.

2. {{error}} - the error response of the previous step.

3. {{params}} - incoming action parameters passed in by components, Execution/Loop action steps, or when calling the action from the code.

4. {{res}} - the response of the request if the step follows an HTTP API step.

5. {{steps.name.data/error}} - the result of a particular action step.

While {{data}} and {{error}} are specific to each step, {{params}} can be accessed in all steps.

Triggering actions

There are multiple ways to trigger actions:

• Automatic:

  • Auto trigger - when the component values used in the first action step change. For example, if the action uses {{ui.input.value}}, it will be triggered when the value of the input is modified.

  • On the first reference - when an action is referenced in the app for the first time, it will be triggered. For example, a table can use {{action.name.data}} to load data from the action - in this case, the action is triggered when the table is rendered for the first time.

• Manual:

  • Component trigger - when action is connected to a built-in component trigger. For example, the button component has an On Click trigger.

  • Execute another action, Loop action - action can be triggered by another action. For example, you can create a loop action that will execute another action multiple times.

  • From code - an action can be called using await {{actions.name.trigger()}} syntax.

  • On Page Load/On App Load - similar to a component trigger, special app and page triggers are available. These triggers allow you to load app configuration and reuse it later on in page actions and components.

  • Execute action button - manually run the action in the development mode while you are developing and testing the action.

  • Proceed from here - manually run the action from a selected step. This is especially useful during development when you want to re-run only a part of the action.

Actions that load data are auto-callable. This means that if you've assigned an action to the Data property of the component, you don't need to trigger the Action. It will be called when the Component is displayed on a page load.

This behavior can be disabled in the Config action section, Execution settings section.

When submitting a form, performing a search, or reloading a table with a button click, you need to assign the action to a particular component trigger:

Assigning an Action

Actions can also be called from any code field using the following syntax:

const users = await {{actions.loadUsers.trigger()}}

You can pass an argument to an Action and it will appear as a {{data}} variable in the first Action step.

{{ actions.loadUsers.trigger({ limit: 10 }) }}

Actions scope

Actions can be page-specific and global. Page-specific actions are executed on a certain page, while global actions are available across the whole app. You can easily convert a page-specific action into a global, or the other way around, just by dragging the action to the corresponding folder.

If you need to assign a page-specific action to another page, move it to the global state first and then transfer it to the necessary page.

When using a global action, the value it holds will be retained across page navigations by default. This means that if you load some configuration settings using a global action, the settings will be accessible on all pages of the app when accessed using {{actions.actionName.data}}.

Using Action result

An action can be assigned to a component using its result as a variable in the code properties and fields:

{{actions.loadUsers.data}}

Using Action result

Any action has two additional variables. They can be used to indicate that an action is loaded, or to access an error that the action was completed with:

{{actions.loadUsers.loading}} // boolean true or false
{{actions.loadUsers.error}} // possible error object

Using the result of a specific step

You can reference the result of a specific step by its name using the syntax {{steps.stepName.data}}. This can be used to utilize the outcome of multiple steps in a single step. Here is an example of using the result of two steps, to map the user's orders to the user object:

const users = {{steps.loadUsers.data}};
const orders = {{steps.loadOrders.data}};

return users.map(user => {
  const userOrders = orders
    .filter(order => order.userId === user.id);

  return {
    ...user,
    userOrders,
  };
});

Double-click the action step to change its name.

Creating a condition

You can also create conditions inside of actions to validate the input before executing a request, for instance:

Adding a condition

Conditions are written in plain JavaScript.

Reusing actions

Actions can be called from the other actions with the help of an Execute action step. It's useful when it comes to reloading data after creating a new item.

By default, the result of a step that goes before the Execute action step will appear as a {{data}} variable in the first step of the Action being called. The result of the Action being called using an Execute action step will appear in the next step that comes right after the Execute action step.

Additionally, you can trigger another action on the Triggers section on success or on error results:

If you have a global action that you'd like to reuse across multiple applications, you can extract it to the Actions Library.

Hotkeys

During development, all actions can be run using the Ctrl + Enter/Cmd + Enter hotkey.

For action steps that have a code editor, such as Code and SQL query, the following hotkeys are supported:

• Ctrl + F/Cmd + F - find in code;

• Ctrl + G/Cmd + G - next find result;

• Shift + Ctrl + F/Cmd + Option + F - find and replace;

• Ctrl + L/Cmd + L - jump to a line;

• Ctrl + Alt + L/Cmd + Option + L - format code.

Action folders

Folders give you a handy way to structure your actions and are especially useful when you have a lot of actions in your application. You can drag the actions to the folder as well as remove them from the folder. You can also add a folder inside another folder.

Action usages

You can check where the action is used with the help of the Usages tab. In the Usages, you can see in which components, other actions, and references the selected action is used. If you click on a specific component or action, you will be transferred to the correspondent settings and able to make the adjustments if required.

Action declaration

If you need to quickly navigate to a certain action, you can do it using a combination Cmd(ctrl)+click. Find the required action, point to its name, Cmd(Ctrl)+click it, and you will be sent to the selected action. The same approach applies to the components.