UI actions

UI actions bridge the gap between multiple UI elements and specific actions, dictating how the interface responds to user interactions. They control behaviors such as displaying loaders, dismissing modals, or sending default data back to a process, enabling interaction between UI components and underlying logic.

Overview

UI actions establish connections between UI components or custom elements and predefined actions. These connections ensure that processes are executed efficiently while defining the UI’s response. Examples include:

• Showing a loader during an action execution.
• Automatically dismissing a modal after a task is completed.
• Sending default data back to the process.

---

Types of UI actions

UI actions can be categorized into two main types:

1. Process UI Actions: Directly interact with process nodes and manual actions.
2. External UI Actions: Perform actions that link to external URLs or open new tabs.

---

Process UI actions

Process UI Actions (labeled ACTION) define how a Button, whether generated or custom, interacts with a manual process action. Before configuring a UI action, ensure the corresponding manual action is set up.

Adding a node action

To configure a UI action, first add a node action (type: manual) to a process node. For detailed steps, refer to:

Adding an action to a node

Example: Configuring a node action (Save Data)

1. Add an Action: Attach an action to a node.
2. Select the Action Type: Choose Save Data, for instance.
3. Action Type: Set it to manual.

Both UI actions and node actions must be configured on the same user task node.

Configuring a UI action

Below are the key configuration options for defining a UI action:

• Event: Define when the action should trigger (Learn about Events).
• Action Type: Specify the type of action (Explore Action Types).
• Node Action Name: Select the corresponding manual action from the dropdown.
• Use a different name for UI action: Optionally, define a unique name to trigger the action in Custom Components.
• Add custom keys: Add custom keys beyond those in the data model.
• Exclude keys: Specify data keys to exclude.
• Add custom body: Provide a default JSON response, merged with additional parameters during execution.
• Add form to submit: Link the action to specific UI elements for validation. Only fields within the selected forms are validated when the action triggers. See Form validation behavior for details.
• Hide Subprocess Navigation: Disable navigation to subprocesses.
• Show loader: Display a loader until a server-side event (SSE) updates the data or screen.

UI actions elements

Events

Events define how user interactions trigger UI actions. The available event types are:

• CLICK: Triggered when a button is clicked.
• CHANGE: Triggered when input fields are modified.

Events are not applicable for UI actions on Custom Components.

---

Action types

The Action Type dropdown includes several predefined options:

• DISMISS: Dismisses a subprocess or closes a modal. Fires immediately with no form validation or data submission. Sets the process and all subprocesses to DISMISSED state (terminal).
• ACTION: Links a UI action to a manual node action.
• START_PROJECT: Initiates a new project instance. This action type is used to trigger a completely new process flow within a different project or application, based on the selected project and process configurations.
• START_WORKFLOW: Triggers an integration workflow directly from a UI button. Available starting with FlowX.AI 5.6.0.
• UPLOAD: Initiates an upload action.
• EXTERNAL: Opens a link in a new browser tab or window.

Dismiss action details

The DISMISS action is the simplest action type. When triggered, it:

1. Calls the backend to dismiss the current process instance
2. Sets the process and all active subprocesses to DISMISSED state — a terminal state with no further processing
3. Sets all active tokens to DISMISSED

Configuration: Only a name and optional analytics parameters are required. Unlike other action types, DISMISS does not support form submission, UI blocking, or custom keys.

The DISMISS action type is only available in process context (User Tasks). It is not available in UI Flows.

Modal dismiss vs DISMISS action: Modals have a separate Dismissible property that controls close-on-backdrop-click and an optional dismiss confirmation alert (with configurable title, message, and button labels). This is a property of the Modal component itself and is independent of the DISMISS UI action type.

---

Start Workflow action details

Available starting with FlowX.AI 5.6.0

The START_WORKFLOW action type lets you trigger an integration workflow directly from a button or other interactive component, without requiring a server-side process action. This bridges UI interactions with integration workflows built in the Workflow Designer.

The START_WORKFLOW action type is configured with the following options:

Option	Description
Workflow	Select the integration workflow to trigger from a dropdown of available workflows in the current application.
Start params	Provide input parameters to pass to the workflow at start time. Supports dynamic values from process data.
Dismiss modal	When the button is placed inside a modal, checking this option automatically dismisses the modal when the action is triggered.

Tab bar components also support a Load UI action, which controls what happens when a tab is selected. This is configured separately at the navigation area level, not through the UI actions panel.

How it works:

When a user clicks a button configured with START_WORKFLOW, the process engine sends a request to the application manager, which locates and starts the specified integration workflow. The workflow runs independently of the current process instance.

The START_WORKFLOW action does not pause the current process or wait for the workflow to complete. It is a fire-and-forget trigger. Design your workflows accordingly if you need to act on workflow results.

---

Form validation behavior

When a UI action has one or more forms linked via Add form to submit, the platform validates all visible, enabled fields in those forms before executing the action. If any field fails validation, the action is blocked and error messages are displayed.

How it works

1. Action triggers

   The user clicks a button (or another event fires) that is linked to a UI action with forms to submit.

2. Forms are resolved

   The platform collects all form controls from the UI elements listed in the Add form to submit configuration.

3. Validation runs

   Each form field is checked against its configured validators. Only fields that are visible and enabled are validated.

4. Action executes or blocks

   If all validated fields pass, the action executes and sends data to the process. If any field fails, the action is blocked and validation errors are shown.

Hidden fields and validation

When a form element is hidden (via a hide condition), its validation is completely disabled. The element’s validators are removed and it is treated as disabled. This means:

• Hidden fields do not block form submission, even if they contain invalid data.
• Validation errors on hidden fields are cleared automatically.
• When the field becomes visible again, validators are re-applied.

This behavior is intentional — it prevents invisible fields from blocking user progress. However, it has an important implication: if you rely on validation for data integrity, ensure that hidden fields either have valid default values or are validated through a separate mechanism (such as a business rule on the backend).

Example scenario:

Field	Visible	Has Required Validator	Blocks Submit?
Full Name	Yes	Yes	Yes, if empty
Email	Yes	Yes	Yes, if invalid
Company Name	Hidden (hide condition)	Yes	No — validation disabled
Phone	Disabled	Yes	No — disabled fields skip validation

Disabled fields and validation

Fields that are explicitly disabled (not via hide condition, but via the disabled property) also skip validation. Both Angular and React SDKs treat disabled fields as valid during form submission.

Scoping validation to specific forms

The Add form to submit option lets you select which UI elements (forms) are validated when the action triggers. This is useful when a screen has multiple forms but only one should be validated for a specific action.

If no forms are selected in Add form to submit, no client-side validation runs — the action executes immediately. Use this intentionally for actions like “Save as Draft” where you want to allow incomplete data.

---

External UI actions

External UI Actions enable linking to external URLs and opening links in a new tab or the same tab.

When configuring an external UI action, additional options become available:

1. URL: Specify the web URL for the action. Supports dynamic values from process data using the ${variableName} syntax.
2. Open in New Tab: Choose whether to execute the action in the current tab or a new tab.

Dynamic URL values

You can include process data values in the URL using the ${variableName} syntax. The placeholders are replaced with actual values from the process data model at runtime.

Examples:

• https://example.com/users/${userId} - Includes a user ID from process data
• https://example.com/documents/${documentId}/view?lang=${language} - Multiple dynamic values
• ${externalSystemUrl}/api/resource - Dynamic base URL from process data

If a referenced variable is not found in the process data, it will be replaced with null.

---

---

Troubleshooting

Validation is not blocking form submission

Symptom: You added validators to form fields but the action still executes with invalid data.

Possible causes:

• The form containing the fields is not listed in Add form to submit on the UI action. Add it to enable validation.
• The fields are hidden by a hide condition. Hidden fields have their validation disabled automatically. Make the fields visible or add backend validation via a business rule.
• The fields are disabled. Disabled fields skip validation.
• No forms are selected in Add form to submit — this means no client-side validation runs at all.

Hidden fields are preventing form submission

Symptom: A form won’t submit even though all visible fields are valid.

Possible causes:

• A field’s hide condition may be evaluating incorrectly, leaving the field visible when you expect it to be hidden. Check the hide expression in the UI Designer.
• The field may be in an error state from before it was hidden. Try clearing the field value before applying the hide condition.

Action not appearing in the dropdown

Symptom: The node action name dropdown is empty when configuring a UI action.

Possible causes:

• No manual action has been added to the current user task node. UI actions can only link to actions of type manual.
• The action is on a different node. Both the UI action and the node action must be on the same user task node.

---

Related resources

Adding an action to a node

How to add and configure node actions

Validators

Configure validation rules for form fields

Buttons

Configure button components that trigger UI actions

Dynamic & computed values

Use expressions for hide conditions and dynamic behavior