# Node actions Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/actions Actions define the activities that a node handles. Actions have various types and specify communication details for plugins or integrations. Node actions are the units of work you attach to a process node: they run business rules, send Kafka messages, push data to the user interface, start subprocesses or integration workflows, upload files, and send notifications. You configure them in the **Actions** tab of a node in the FlowX.AI Designer. Node actions allow you to incorporate **business rules** into a **process**, and send data to front-end apps. The FlowX.AI platform supports the following **types of node actions**: You can only define and add actions on the following types of **nodes**: [**send message task**](../node/message-send-received-task-node#send-message-task), [**task**](../node/task-node) and [**user task**](../node/user-task-node). Actions fall into two categories: * Business rules * User interactions ### Business rules Actions use action rules such as MVEL expressions or scripts in JavaScript, Python, or Groovy to attach business rules to a node. For more information about supported scripting languages, see Supported scripts. Each button on the user interface corresponds to a manual user action. ### Action edit When configuring an action, the Action Edit panel provides three main configuration sections: #### Trigger This section defines how and when you can execute the action: * **Manual**: Requires manual triggering through the REST API, typically by a user interaction in the interface (for example, clicking a button). When turned off, the action runs automatically. * **Repeatable**: When enabled, you can trigger the action multiple times. When turned off, you can execute the action only once. Manual actions can be either mandatory or optional. Automatic actions are always considered mandatory. #### Execution This section controls the action's execution behavior: * **Optional**: When enabled, the action is optional and the flow can advance without executing it. When turned off (default), the action is mandatory. * **Autorun Children?**: When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/node_action.png) If all mandatory actions on a node are not executed, the flow (token) doesn't advance. #### Navigation This section controls user navigation behavior: * **Allow back to this action**: Returns the token to this action from a downstream node only if you trigger the action manually. When enabled, you have the following "Back in steps" configuration options available: * **When returning to this action, reset process data**: Restores the process state and data to how it was before the initial execution of this action. Default is off. * **Copy the following objects from current state**: Specifies process keys that retain their data as persisted before you navigate back to this action. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_back_in_action.png) ### Action parameters Action parameters store extra values as key/value pairs, such as topics for outgoing messages or message formats for the front-end. ## Configuring actions Beyond the basic trigger, execution, and navigation settings described in the preceding section, actions have additional characteristics: ### Action order When multiple actions exist on a single node, the system executes them in the order you define them. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/%20node_action1.png) ### Parent/child hierarchy Actions can be organized in a parent/child hierarchy, allowing you to create dependent action chains. Child actions can be configured to: * Run automatically after the parent completes (using **Autorun Children?**): When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off. * Execute as callbacks when responses are received from external systems For more information on adding and managing actions, see the following section: ## Linking actions together You can link actions together in two ways so that certain actions run immediately after others: Certain actions can run immediately after another action by setting the `parentName` field on the action for callbacks. Callback actions are performed when the Engine receives a specific message, indicated by the `callbacksForAction` header in the message. To run actions immediately after the parent action, set the `autoRunChildren` flag to `true` for the parent action. ### Child actions A parent action has a flag `autoRunChildren`, set to `false` by default. When you set this flag to `true`, the child actions (the ones defined as mandatory and automatic) run immediately after the parent action completes execution. ![Action Edit settings with Autorun Children switched on](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/17-autorun_children.png) ### Callback actions You can mark child actions as callbacks to run after receiving a reply from an external system. Set these actions when defining the interaction with the external system (the [Kafka send action](../node/message-send-received-task-node#configuring-a-send-message-task)). For example, you can use a callback function to handle a user's interaction with a web page, such as uploading a file. When the user performs the action, the callback function executes, allowing the web app to respond appropriately. ![Upload File action headers with callbacksForAction set to the parent action name](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/03b-upload_config_b_headers.png) #### Example Add callback actions in the **Advanced configuration** tab, in the **header** parameter `callbacksForAction`. ```js theme={"dark"} {"processInstanceId": ${processInstanceId}, "destinationId": "upload_file", "callbacksForAction": "upload_file"} ``` * `callbacksForAction`: The value of this key is a string that specifies a callback action associated with the `upload_file` destination ID. This is part of an event-driven system (Kafka send action) where the system calls this callback after the `upload_file` action completes. * `destinationId`: The name of the node that receives the reply. `callbacksForAction` holds the name of the parent action: when the reply arrives, the engine runs that action's child actions. # Append params to parent process Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/append-params-to-parent-process It is a type of action that allows you to send data from a subprocess to a parent process. **Why is it important?** If you are using subprocesses that produce data that needs to be sent back to the main **process**, you can do that by using an **Append Params to Parent Process** action. This action writes data into the **parent process data model** permanently. To push real-time updates to the parent UI without modifying the data model, use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent. For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent). ## When to use this action In a synchronous subprocess (Start Async = OFF on the Start Subprocess action), prefer **Data Mapping** on the Start Subprocess action — it propagates results back to the parent automatically when the subprocess ends, without an extra action. Append Params to Parent Process is the right choice when: * **The subprocess runs asynchronously** (Start Async = ON on the Start Subprocess action). The parent doesn't wait for the subprocess to finish, so Data Mapping doesn't apply — the subprocess must push results to the parent itself. * **The subprocess is long-running** (LLM agents, slow integrations, batch jobs) and you want fire-and-forget execution while the user continues in the UI. ![Main process with two async subprocesses started in parallel before a converging gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_1.png) ### Combined with Send data to user interface To both persist the result AND notify the user's UI in a single step, attach two actions to the final node of the async subprocess: 1. **Append Params to Parent Process** — writes the result into the parent's data model. 2. **Send data to user interface** with Target Process set to Parent — pushes a UI update over SSE. This is the standard pattern for async agent results: data is persisted so downstream nodes can read it, and the user sees the update appear without refreshing. ![Two actions configured on the final node of an async subprocess — Append Params to Parent Process and Send data to user interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_2.png) ## Configuring an Append params to parent process After you create a process designed to be used as a [subprocess](../process/subprocess), you can configure the action. To do this, you need to add an **Append Params to Parent Process** on a [**Task node**](../node/task-node) in the subprocess. The following properties must be configured: * [Action Edit](#action-edit) * [Parameters](#parameters) * [Data to send (for Manual actions)](#data-to-send) ### Action edit * **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find. * **Action Type** — set to **Append Params to Parent Process**. The remaining options are grouped into three columns: **Trigger** * **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node. For Append Params, leave this OFF in most cases. * **Repeatable** — when ON, the action can be triggered multiple times. **Execution** * **Optional** — automatic actions cannot be optional. Manual actions can be optional or required. * **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes. **Navigation** * **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process). ### Parameters All three fields below are mandatory. * **Copy from current state** - data that you want to be copied back to the parent process * **Destination in the parent state** - on what key to copy the param values * **Show Target Process** - ID of the parent process where the params are written. Set this to `${parentProcessInstanceId}` if the variable was defined when you [started the subprocess](./start-subprocess-action). If this value is missing or cannot be parsed as a process instance ID, the action raises a `MISSCONFIG_SUBPROCESS` incident on the parent process — it does not fail silently. To recap: if you have a **Copy from current state** with a simple **JSON** -`{"age": 17}`, that needs to be available in the parent process, on the `application.client.age` key, you will need to set this field (**Destination in the parent state**) with `application.client`, which will be the key to append to in the parent process. **The payload always lands at the destination key — don't repeat the key in both fields.** If **Copy from current state** is `{"clickCount": ${clickCount}}` and **Destination in the parent state** is `clickCount`, the parent receives a nested object at `clickCount.clickCount`, not the value at `clickCount`. To write a single value to a top-level parent key, use a raw value reference instead: set **Copy from current state** to `${clickCount}` and **Destination in the parent state** to `clickCount`. Raw references work for numbers, booleans, objects, and arrays; wrap string values in quotes (`"${myKey}"`). **The action replaces the value at the destination key.** If the destination key already contains a nested object — for example `application.client = {"name": "Alice", "age": 30}` — sending `{"age": 35}` to destination `application.client` overwrites the entire object and `name` is lost. To preserve siblings, write to a destination key that doesn't conflict with existing parent state (for example, `application.subprocessResult.client` instead of `application.client`), or use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent for non-destructive updates. ### Data to send * **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](../node/user-task-node) section) **Data to send** is configurable only when the **Manual** toggle is ON. ## Example We have a subprocess that allows us to enter the age of the client on the **data.client.age** key, and we want to copy the value back to the parent process. The key to which we want to receive this value in the parent process is **application.client.age**. This is the configuration to apply the above scenario: **Parameters** * **Copy from current state** - `{"age": ${data.client.age}}` — the JSON payload to send to the parent * **Destination in the parent state** - `application.client` — the key on the parent where the payload is written. Combined with the payload above, the value lands at `application.client.age`. * **Show Target Process** - `${parentProcessInstanceId}` — required, identifies the parent process # Business rules types Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action A business rule is an action type in FlowX.AI that allows you to configure a script on a BPMN node. It's a way to specify business logic or decision-making processes in a business process. The script can read and write the data available on the process at the moment the script is executed. For this reason, it is very important to understand what data is available on the process when the script is executed. Business rules can be attached to a node by using actions with [**action rules**](../actions#business-rules) on them. These can be specified using MVEL expressions, or scripts written in JavaScript, Python, or Groovy. ![Business rule action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/business_rule_action.png) For more information about supported scripting languages, see the next section: You can also test your rules by using the **Test Rule** function. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/test_rule_function.png) ## Configuration To use a Business Rules Action, follow these steps: 1. **Select a BPMN Task Node**: Choose the BPMN task node to which you want to attach the Business Rules Action. This could be a Service Task, User Task, or another task type that supports actions. 2. **Define the Action**: In the task node properties, configure the "Business Rules Action" field and select the desired language (MVEL, Java, JavaScript or Python). 3. **Write the Business Rule**: In the selected language, write the business rule or decision logic. This rule should take input data, process it, and possibly generate an output or result. 4. **Input and Output Variables**: Ensure that the task node can access the necessary input variables from the BPMN process context and store any output or result variables as needed. 5. **Execution**: When the BPMN process reaches the task node, the attached Business Rules Action is executed, and the defined business rule is evaluated. 6. **Result**: The result of the business rule execution may affect the flow of the BPMN process, update process variables, or trigger other actions based on the logic defined in the rule. The script's `output` is merged into the existing process data, not written over it: keys the script doesn't write keep their values, and writing `{}` to an existing object changes nothing. To clear a key, set it to `null`. For the full merge rules, see [How output is merged into process data](../../supported-scripts#how-output-is-merged-into-process-data). ### Script engine per rule **Available starting with FlowX.AI 5.9.1.** Each business rule can run on either the current **native** script engine (the 5.9 default) or the legacy **GraalVM** engine, selected per rule. This lets you migrate scripts to native one at a time instead of all at once. * **Rules created before the move to native** keep running on **GraalVM**, and the engine selector is available so you can switch them to native after testing. * **New rules** run on **native** by default; the selector only appears for rules that support GraalVM. * On platforms configured for native-only execution, the selector is hidden and all rules run on native. The platform-wide default engine is set separately — see [Supported scripts](../../supported-scripts). ### Script size and execution limits JavaScript and Python rules that run on the native script engine are bounded by the worker pool limits of the process engine: | Limit | JavaScript default | Python default | Environment variable | | - | - | - | - | | Max input payload size | `1048576` bytes (1 MB) | `1048576` bytes (1 MB) | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` / `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | | Execution timeout per script | `5000` ms | `10000` ms | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` / `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | The input payload includes the process data passed to the script. A large data model can exceed the payload limit even when the script is short. When this happens, the rule fails with an error stating that the request payload exceeds `maxPayloadSizeBytes`. To fix it, reduce the data passed to the script or ask your platform administrator to raise the limit for the affected language. See [Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration). Let's take look at the following example. We have some data about the gender of a user and we need to create a business rule that computes the formal title based on the gender: 1. This is how the process instance data looks like before it reaches the business rule: ```json theme={"dark"} { "application" : { "client" : { "firstName" : "David", "surName" : "James", "gender" : "M", } } } ``` 2. When the token reaches this node the following script (defined for the business rule) is executed. The language used here for scripting is MVEL. ```java theme={"dark"} if (input.application.client.gender == 'F') { output.put("application", { "client": { "salutation": "Ms" } }); } else if (input.application.client.gender == 'M') { output.put("application", { "client": { "salutation": "Mr" } }); } else { output.put("application", { "client": { "salutation": "Mx" } }); } ``` 3. After the script is executed, the process instance data will look like this: ```json theme={"dark"} { "application": { "client": { "firstName": "David", "surName": "James", "gender": "M", "salutation": "Mr" } } } ``` ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example.gif) ## Flattened vs unflattened keys With version [**2.5.0**](https://old-docs.flowx.ai/release-notes/v2.5.0-april-2022/) we introduced unflattened keys inside business rules. Flattened keys are now obsolete. You are notified when you need to delete and recreate a business rule so it contains an unflattened key. ![Obsolete business rule](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/obsolete_business_rule.png) ## Business rules examples Examples available for [**v2.5.0**](https://old-docs.flowx.ai/release-notes/v2.5.0-april-2022/) version and higher We will use the MVEL example used above to rewrite it in other scripting languages formats: ```Java theme={"dark"} if (input.application.client.gender == 'F') { output.put("application", { "client": { "salutation": "Ms" } }); } else if (input.application.client.gender == 'M') { output.put("application", { "client": { "salutation": "Mr" } }); } else { output.put("application", { "client": { "salutation": "Mx" } }); } ``` ```python theme={"dark"} if input.get("application").get("client").get("gender") == "F": output.put("application", { "client" : { "salutation" : "Ms" } }) elif input.get("application").get("client").get("gender") == "M": output.put("application", { "client" : { "salutation" : "Mr" } }) else: output.put("application", { "client" : { "salutation" : "Mx" } }) ``` ```js theme={"dark"} if (input.application.client.gender === 'F') { output.application = { client: { salutation: 'Ms' } }; } else if (input.application.client.gender === 'M') { output.application = { client: { salutation: 'Mr' } }; } else { output.application = { client: { salutation: 'Mx' } }; } ``` ```groovy theme={"dark"} if (input.application.client.gender === 'F') { def gender = input.application.client.gender switch (gender) { case 'F': output.application = [client: [salutation: 'Ms']] break case 'M': output.application = [client: [salutation: 'Mr']] break default: output.application = [client: [salutation: 'Mx']] } ``` # Extracting additional data in business rules Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/extracting-additional-data Business rules in FlowX.AI allow you to extract and use key values dynamically. This is essential for handling user security details, configuration parameters, and business logic calculations. Business rules can read more than the process data model: at execution time the platform injects additional runtime data, such as the current user's security details and configuration parameters, that your scripts can extract and use. This page shows how to retrieve security details, extract specific user attributes, and fetch configuration parameters from a business rule. This guide is covering the following: ✅ Retrieving security details dynamically\ ✅ Extracting specific user attributes\ ✅ Fetching configuration parameters ## Extracting security details Security details (`securityDetails`) store user-related data, including **email, username, roles, and permissions**. These values are stored in `additionalData.securityDetails` and can be accessed dynamically within business rules and workflow scripts. The `securityDetails` structure differs between **processes** and **workflows**. Processes group security details by swimlane and role, while workflows use a simplified flat structure. See the tabs below for both formats. **Test mode behaves differently from runtime.** `additionalData` (including `securityDetails`) is populated by the platform at execution time, so its availability when you use the **Test** action depends on the context: * **Process business rule Test:** `additionalData` is injected automatically when the rule runs, so `securityDetails` resolves the same way it does at runtime. * **Workflow script Test:** `additionalData` is not injected automatically. To test a script in isolation, add the `securityDetails` structure manually to the test input. Without it, the script works during a full workflow run but returns no security details when run through **Test** alone. ### Retrieve security details Use the following business rule to fetch and store security details: ```JavaScript theme={"dark"} // Retrieve security details from additionalData securityDetails = additionalData.get("securityDetails"); // Store the extracted security details output.put("securityDetails", securityDetails); ``` ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2813%29.png) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-25%20at%2013.32.37.png) Example output: ```json theme={"dark"} { "securityDetails": { "Default": { "owner": { "username": "user@email.com", "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600", "details": { "firstName": "John", "lastName": "Snow", "email": "user@email.com", "jwt": "your_jwt", "roles": [], "groups": [ "/Users/Flowx_demo", "/superAdmin" ], "attributes": {} } } } } } ``` In processes, `securityDetails` is grouped by **swimlane name** (e.g., `Default`) and **role** (e.g., `owner`). This structure reflects the BPMN swimlane and role assignments configured in the process definition. ### Extract specific owner details To retrieve specific attributes, such as email, username, first name, and last name, use one of the following scripts (JS or Python): ```javascript theme={"dark"} // Retrieve security details securityDetails = additionalData.get("securityDetails"); // Extract owner details from the Default swimlane email = securityDetails.Default.owner.details.email; username = securityDetails.Default.owner.username; firstName = securityDetails.Default.owner.details.firstName; lastName = securityDetails.Default.owner.details.lastName; // Store extracted details in the output output.put("email", email); output.put("username", username); output.put("firstName", firstName); output.put("lastName", lastName); ``` ```python theme={"dark"} # Retrieve security details security_details = additionalData.get("securityDetails") # Extract owner details from the Default swimlane email = security_details["Default"]["owner"]["details"]["email"] username = security_details["Default"]["owner"]["username"] first_name = security_details["Default"]["owner"]["details"]["firstName"] last_name = security_details["Default"]["owner"]["details"]["lastName"] # Store extracted details in the output output["email"] = email output["username"] = username output["firstName"] = first_name output["lastName"] = last_name ``` Extracted values: * **Owner Email** (`securityDetails.Default.owner.details.email`) * **Username** (`securityDetails.Default.owner.username`) * **First Name** (`securityDetails.Default.owner.details.firstName`) * **Last Name** (`securityDetails.Default.owner.details.lastName`) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2814%29.png) ### Dynamic extraction by swimlane If your application uses multiple swimlanes, retrieve the owner details dynamically: ```JavaScript theme={"dark"} // Get security details securityDetails = additionalData.get("securityDetails"); // Extract owner details based on the swimlane ownerDetails = securityDetails.Default.owner.details; Default is the swimlane name in this example. Replace it with your swimlane name. // Store extracted values in the process instance output.put("email", ownerDetails.email); output.put("username", securityDetails.Default.owner.username); output.put("firstName", ownerDetails.firstName); output.put("lastName", ownerDetails.lastName); ``` Example output: ```json theme={"dark"} { "email": "user@email.com", "username": "user@email.com", "firstName": "John", "lastName": "Snow" } ``` ### Retrieve security details In workflow scripts, `securityDetails` uses a **flat structure** — there is no swimlane or role grouping, since workflows do not have swimlanes. ```javascript theme={"dark"} // Retrieve all additional data const additionalParams = additionalData; // Access security details directly output.put("securityDetails", additionalParams.securityDetails); ``` Example output: ```json theme={"dark"} { "securityDetails": { "username": "user@email.com", "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600", "details": { "firstName": "John", "lastName": "Snow", "email": "user@email.com", "roles": ["ROLE_ADMIN", "ROLE_USER"], "groups": ["/Users/Flowx_demo", "/superAdmin"], "attributes": {} } } } ``` | Field | Description | | - | - | | `username` | The authenticated user's username | | `identifier` | The user's unique identifier (Keycloak subject ID) | | `details.firstName` | User's first name | | `details.lastName` | User's last name | | `details.email` | User's email address | | `details.roles` | Roles assigned to the user in the authentication token | | `details.groups` | Groups the user belongs to in the authentication token | | `details.attributes` | Additional user attributes from the authentication token (empty object if none are set) | Unlike process `securityDetails`, workflows do not include the `jwt` field, and they use a flat structure (no swimlane or role grouping). ### Extract specific user details Since the structure is flat, you can access user attributes directly without navigating swimlane or role levels: ```javascript theme={"dark"} // Retrieve security details securityDetails = additionalData.securityDetails; // Extract user details directly (no swimlane grouping) email = securityDetails.details.email; username = securityDetails.username; identifier = securityDetails.identifier; firstName = securityDetails.details.firstName; lastName = securityDetails.details.lastName; roles = securityDetails.details.roles; groups = securityDetails.details.groups; // Store extracted details in the output output.put("email", email); output.put("username", username); output.put("identifier", identifier); output.put("firstName", firstName); output.put("lastName", lastName); output.put("roles", roles); output.put("groups", groups); ``` ```python theme={"dark"} # Retrieve security details security_details = additionalData["securityDetails"] # Extract user details directly (no swimlane grouping) email = security_details["details"]["email"] username = security_details["username"] identifier = security_details["identifier"] first_name = security_details["details"]["firstName"] last_name = security_details["details"]["lastName"] roles = security_details["details"]["roles"] groups = security_details["details"]["groups"] # Store extracted details in the output output["email"] = email output["username"] = username output["identifier"] = identifier output["firstName"] = first_name output["lastName"] = last_name output["roles"] = roles output["groups"] = groups ``` Extracted values: * **Email** (`securityDetails.details.email`) * **Username** (`securityDetails.username`) * **Identifier** (`securityDetails.identifier`) * **First Name** (`securityDetails.details.firstName`) * **Last Name** (`securityDetails.details.lastName`) * **Roles** (`securityDetails.details.roles`) * **Groups** (`securityDetails.details.groups`) ### Structure comparison | Field | Process path | Workflow path | | - | - | - | | Email | `securityDetails.Default.owner.details.email` | `securityDetails.details.email` | | Username | `securityDetails.Default.owner.username` | `securityDetails.username` | | Identifier | `securityDetails.Default.owner.identifier` | `securityDetails.identifier` | | First Name | `securityDetails.Default.owner.details.firstName` | `securityDetails.details.firstName` | | Last Name | `securityDetails.Default.owner.details.lastName` | `securityDetails.details.lastName` | | Roles | `securityDetails.Default.owner.details.roles` | `securityDetails.details.roles` | | Groups | `securityDetails.Default.owner.details.groups` | `securityDetails.details.groups` | | Attributes | `securityDetails.Default.owner.details.attributes` | `securityDetails.details.attributes` | | JWT | `securityDetails.Default.owner.details.jwt` | Not available | If you are migrating business rule logic from a process to a workflow, update the `securityDetails` access paths. The swimlane (e.g., `Default`) and role (e.g., `owner`) levels do not exist in the workflow structure. *** ## Extracting values from configuration parameters To make business rules flexible, store configuration values in project configuration parameters instead of hardcoding them. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2816%29.png) ### Retrieve configuration parameters Use a business rule to fetch and store configuration parameter values dynamically: ```JavaScript theme={"dark"} // Retrieve a configuration parameter (e.g., commission percentage) commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage"); // Store the retrieved value in output in the process instance output.put("commissionPercentage", commissionPercentage); ``` ### Example use case: commission calculation This example shows how to calculate a commission value dynamically using a configuration parameter. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.54.47.png) #### Configuration parameters | **Parameter Name** | **Description** | **Example Value** | | - | - | - | | `commissionPercentage` | The percentage used to calculate the commission | `0.05` (5%) | Configuration parameters can be modified in: ➡ FlowX.AI Designer → Your Project → Configuration Parameters #### Process flow In a User task we have an input UI element where the user provides an amount (`userInputAmount`). ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.56.41.png) In the next node, a Service Task fetches the `commissionPercentage` from the configuration parameters. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.59.57.png) Business rule used: ```JavaScript theme={"dark"} // Retrieve user input amount = input.get("userInputAmount"); // Retrieve a value from configuration commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage"); // Apply the configuration value commissionValue = amount * commissionPercentage; // Store the calculated result in the process instance output.put("commissionValue", commissionValue); ``` Formula used to calculate the commission: $$ \text{commissionValue} = \text{userInputAmount} \times \text{commissionPercentage} $$ The computed `commissionValue` is stored for further processing. Final result: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-27%2014.21.53.gif) Why Use Configuration Parameters? ✅ Keep business rules flexible by avoiding hardcoded values.\ ✅ Adapt calculations dynamically based on environment settings.\ ✅ Simplify updates by modifying values in the project configuration rather than editing business rules. # Kafka send action Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/kafka-send-action The FlowX.AI Designer offers various options to configure the Kafka Send Action through the Actions tab at the node level. The Kafka send action publishes a message from a process node to a Kafka topic, which is how a process communicates asynchronously with plugins and external systems. You configure it in the **Actions** tab at the node level in the FlowX.AI Designer, in two parts: * [Action Edit](#action-edit) * [Parameters](#parameters) ![Kafka Send Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/kafka_send_action_confg.gif) ### Action Edit * **Name** - Used internally to distinguish between different [actions](../actions/actions) within the process. Establish a clear naming convention for easy identification. * **Order** - Sets the running order for multiple actions on the same node. * **Timer Expression** - Enables a delay, using [ISO 8601 duration format](../node/timer-events/timer-expressions#iso-8601) (e.g., `PT30S` for a 30-second delay). * **Action Type** - Designate as **Kafka Send Action** for sending messages to external systems. * **Trigger Type** - **Automatic** by default: the action runs when the process reaches the node. Set it to **Manual** to run the action only when it is triggered, for example by a button. Kafka Send actions are **Automatic** by default. To send the message on a user interaction instead, turn on **Manual** and bind the action to a button through a UI action. For how manual actions work, see [Trigger](../actions/actions#trigger). * **Required Type** (Mandatory/Optional) - **Automatic** actions are typically set as **mandatory**. Manual actions can be either mandatory or optional. * **Repeatable** - Allows triggering the action multiple times if required. * **Autorun Children** - When activated, child actions (mandatory and automatic) execute immediately after the parent action concludes. ### Parameters You can add parameters via the **Custom** option or import predefined parameters from an integration. For detailed information on **Integrations management**, refer to [**this link**](../../platform-deep-dive/integrations/integration-designer). * **Topics** - Specifies the Kafka topics listened to by the external system for requests. * **Message** - Contains the message payload to be dispatched. * **Advanced Configuration (Headers)** - Represents a JSON value sent within the Kafka message headers. ![Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/message_send_parameters.png) ## Dynamic Kafka topics You can use dynamic topic names for Kafka Send and Kafka Receive actions in FlowX.AI processes by leveraging Configuration Parameters. This enables flexibility when working with Kafka topics across different environments or use cases. Steps to Create Dynamic Kafka Topics: Navigate to **Projects → Your Project → Configuration Parameters** in FlowX.AI Designer. Add or update configuration keys for Kafka topics. Example: * Key: `kafka_send_2` * Value: `ai.flowx.plugin.document.trigger` * Key: `kafka_receive` * Value: `ai.flowx.engine.receive.plugin.document` ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2017.47.57.png) This allows referencing these parameters dynamically in your Kafka actions. Open the process where you want to configure the Kafka Send Action. Go to Node Config > Actions. Select Kafka Send Action as the action type. Under Parameters, locate the Topics field. Use a dynamic reference to concatenate a parameter with another value: `${kafka_send_2}.${topic2}` Here: * `${kafka_send_2}` dynamically pulls the value from Configuration Parameters. * `${topic2}` can be another dynamic input set within the process. Define the JSON structure for the message payload. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2018.03.36.png) Ensure that all required fields align with the expected schema of the consuming system. Start the process and check whether messages are correctly sent to the Kafka topic. If needed, modify the configuration parameters to change the topic dynamically. ## Kafka send action scenarios The Kafka Send action serves as a versatile tool that facilitates communication across various systems and plugins, enabling efficient data transfer, reliable document management, notifications, and process initiation. This action finds application in numerous scenarios while configuring processes: * **Communicating with External Services** * **Interacting with Connectors** - For example, integrating a connector in the FlowX.AI Designer [here](../../platform-deep-dive/integrations/building-a-connector#integrating-a-connector-in-flowx-ai-designer). * **Engaging with Plugins:** * **Document Plugin:** * Generating, uploading, converting, and splitting documents - Explore examples [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview). * Updating/deleting documents - Find an example [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file) * Optical Character Recognition (OCR) integration - View an example [here](../../platform-deep-dive/plugins/custom-plugins/ocr-plugin#scenario-for-flowx-ai-generated-documents). * **Notification Plugin:** * Sending notifications - Example available [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification) and emails with attachments [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments). * One-Time Password (OTP) generation and validation - Refer to these examples for [generating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/generate-otp) and [validating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/validate-otp) an OTP. * Forwarding notifications to external systems - Explore this [example](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/forwarding-notifications-to-an-external-system). * **OCR Plugin** * **Customer Management Plugin** * **Task Management Plugin:** * Bulk operations update - Find an example [here](../../platform-deep-dive/core-extensions/task-management/task-management-overview#bulk-updates). * **Requesting Process Data for Forwarding or Processing** - For example, Data Search [here](../../platform-deep-dive/core-extensions/search-data-service). * **Initiating Processes** - Starting a process via Kafka. Find examples [here](../../flowx-designer/managing-a-project-flow/starting-a-process). The Kafka Send action stands as a versatile facilitator, enabling smooth operations in communication, document management, notifications, and process initiation across diverse systems and plugins. # Send data to user interface Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-data-to-user-interface Push real-time updates from the process to the client over a single long-lived HTTP connection using Server-Sent Events (SSE). The Send data to user interface action pushes data from the process to the front-end app in real time, over Server-Sent Events (SSE). Use it when a screen must react to something that happened in the process, such as displaying a computed result or refreshing state, without the user reloading anything. This action pushes data to the **UI only** via SSE. It does not modify the parent process data model. To persist data from a subprocess into the parent process, use [Append Params to Parent Process](./append-params-to-parent-process). For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent). ## Configuring a Send data to user interface action Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure a Send data to user interface, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node), which has the following configuration options: * [Action Edit](#action-edit) * [Parameters](#parameters) * [Data to send (for Manual actions)](#data-to-send) ### Action Edit * **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find. * **Action Type** — set to **Send data to user interface**. The remaining options are grouped into three columns: **Trigger** * **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node. * **Repeatable** — when ON, the action can be triggered multiple times. **Execution** * **Optional** — automatic actions cannot be optional. Manual actions can be optional or required. * **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes. **Navigation** * **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process). ![Send data to user interface action edit panel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_1.png) ### Parameters The following fields are required for a minimum configuration of this type of action: * **Message Type** — one of four options. Each maps to a distinct SSE `messageType` on the wire: * **Default** (sent as `data`) — push a JSON payload to the UI. Most common case. * **Action** (sent as `runAction`) — tell the UI to perform an action. The Message must define a `type` field set to one of the supported [action types](../ui-designer/event-handlers#action-types) (`DISMISS`, `ACTION`, `START_PROCESS_INHERIT`, `UPLOAD`, `EXTERNAL`). * **General** (sent as `generalData`) — push the process's general data (configured under **Process Settings → General**) to the UI. * **Process Metadata** (sent as `processMetadata`) — push process instance metadata to the UI. To start a new process from a Send data to user interface action, set **Message Type** to **Action** and define a **Message** with the following format: ```json theme={"dark"} { "processName": "demoProcess", "type": "START_PROCESS_INHERIT", "clientDataKeys":["webAppKeys"], "params": { "startCondition": "${startCondition}", "paramsToCopy": [] } } ``` * `paramsToCopy` — choose which keys from the parent process parameters are copied to the subprocess * `withoutParams` — choose which keys from the parent process parameters are excluded when copying * **Message** — the JSON payload to send. You can use constant values and substitutions from process instance data. * **Replace Values** — toggle next to the Message field, ON by default. When ON, `${...}` placeholders in the message are replaced with the corresponding values from process instance data before the message is sent. When OFF, the message is sent as literal text, with `${...}` placeholders left unresolved. The same toggle appears on other action parameters (for example, on Start Subprocess) and behaves the same way: it controls placeholder substitution for that parameter, before the action executes. * **Target Process** — the running process instance the message is sent to. Options: **Active process** (`${processInstanceUuid}`) or **Parent process** (`${parentProcessInstanceUuid}`). When this action runs inside a subprocess (started via [Start Subprocess](./start-subprocess-action), a [Call activity node](../node/call-subprocess-tasks/call-activity-node), or an embedded subprocess), set **Target Process** to **Parent process** to push the message to the user's UI session bound to the parent process. ### Data to send * **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User task configuration](../node/user-task-node) section) **Data to send** is configurable only when the **Manual** toggle is ON. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/websocket_data_to_send.gif) ### Send update data example To send the latest value from the [process instance](../../projects/runtime/active-process/process-instance) data found at `application.client.firstName` key, to the frontend app, you can do the following: 1. Add a **Send data to user interface**. 2. Set the **Message Type** to **Default** (this is default value for `data`). 3. Add a **Message** with the data you want to send: * `{ "name": "${application.client.firstName}" }` 4. Choose the **Target Process**. ![Send data to user interface — Message and Target Process configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_2.png) # Send notification action Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-notification-action Send emails directly from process nodes using the Send Notification action. Supports both new outbound emails and replies to received emails. ## Overview The Send Notification action enables process nodes to send emails directly through a predefined email connection. It supports two modes: * **New email mode** - Send a new email to specified recipients * **Reply mode** - Reply to an email that triggered the process (using data from an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) data source) This differs from the existing [Kafka send](../node/message-send-received-task-node) notification approach in how you configure it, not in how the email is delivered: instead of hand-crafting the request payload in a Kafka send action, you fill in typed fields and the action builds the request for you. Both approaches hand the request to the Notifications Plugin, which sends the email through the email connection set on the notification template, an [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source. Notification templates configured before this feature for Kafka-based sending continue to work without modification. **Recommended for new processes.** The Send Notification action provides typed, validated configuration fields and is the simpler choice for outbound emails. The [Kafka-based sending guide](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments) remains fully supported for existing processes and advanced cases where you need to craft the notification payload yourself. *** ## Prerequisites Before using the Send Notification action, ensure you have: 1. An [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source configured in Integration Designer (or a Default Server configured at the environment level) 2. A [notification template](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates) with **Email Server** set to **Predefined Email Connection** *** ## Adding the action The Send Notification action is available on the following node types: * [Send Message Task](../node/message-send-received-task-node#send-message-task) * [Task](../node/task-node) * [User Task](../node/user-task-node) To add the action: 1. Select a node in your process definition 2. Open the **Actions** tab 3. Click **Add action** 4. Set **Action type** to **Send Notification** ![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et1.png) *** ## Configuration ### Notification template Select the notification template to use for the email content. Only notification templates with **Email Server** set to **Predefined Email Connection** appear in this list. ### Data mapping The **Data Mapping** section contains the email delivery settings, starting with the reply toggle. Toggle this setting to reply to the email that started the process. **Default:** OFF When enabled, the reply is sent only to the original sender unless you configure CC or BCC Receivers. The subject is automatically set to `RE: `. *** ## Reply mode (reply toggle ON) When **Reply to received emails** is enabled, the action replies to the email that triggered the current process instance. The email is sent to the original sender, and the subject is automatically prefixed with `RE:`. The process variable key that contains the `headerParams` object from the original email received through an [Email Trigger](../../platform-deep-dive/integrations/email-trigger). **Example:** `${replyField}` The `headerParams` object includes the `Message-ID` and other headers from the original email, which are required to maintain the email conversation thread. The process variable key that resolves to a language code for the notification template. **Examples:** `en`, `ro`, `fr` Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`. Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape. Each attachment requires: * `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path * `filename` — name shown to the recipient **Example:** ```json theme={"dark"} [{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}] ``` ![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png) On SMTP, omitting `filename` results in an unnamed attachment. Always set it. The recipients for the reply. If left empty, the reply is automatically sent to the original sender (`emailMessage.sender`). Use a process variable or explicit list to override. **Example:** `${emailMessage.sender}` For multiple addresses, enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. CC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. Original CC recipients are **not** preserved automatically. If this field is empty, the reply is sent without any CC. To reply-all, pass `${emailMessage.cc}` explicitly (or build your own list). BCC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. BCC recipients from the original email are not visible on incoming messages and cannot be inherited. Set this field explicitly if you need BCCs on the reply. Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template. *** ## New email mode (reply toggle OFF) When **Reply to received emails** is turned off, the action sends a new email to the specified recipients. The process variable key that resolves to a language code for the notification template. **Examples:** `en`, `ro`, `fr` Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`. Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape. Each attachment requires: * `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path * `filename` — name shown to the recipient **Example:** ```json theme={"dark"} [{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}] ``` ![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png) On SMTP, omitting `filename` results in an unnamed attachment. Always set it. The recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. CC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. BCC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list. Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template. ![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et2.png) *** ## Example: Reply to a customer email This example shows a complete flow where an incoming email triggers a process, and the process replies to the sender. Configure an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) data source to monitor incoming emails (for example, `support@company.com`). Configure an [Email Sender](../../platform-deep-dive/integrations/email-sender) data source with SMTP credentials for outbound emails. Create a notification template for the reply email: 1. Set **Email Server** to **Predefined Email Connection** 2. Set **Email Sender** to your Email Sender data source 3. Design the reply content using the template editor Create a process with: * A **Message Start Event** configured with the Email Trigger * Processing nodes for your business logic (for example, classify the email, look up customer data) * A node with the **Send Notification** action configured in reply mode On the appropriate node: 1. Set **Action type** to **Send Notification** 2. Select your notification template 3. Toggle **Reply to received emails** to **ON** 4. Set **Reply to Email Header** to the process variable containing the original email's header params (for example, `${replyField}`) 5. Set **Receivers** to `${emailMessage.sender}` 6. Set **Language** to the appropriate language code (for example, `en`) When an email arrives, the process starts automatically, runs your business logic, and sends a reply to the original sender — maintaining the email conversation thread. *** ## Related resources Configure SMTP connections for sending emails Configure IMAP connections to trigger processes from incoming emails Create and manage email notification templates Learn about all available action types # Start integration workflow action Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-integration-workflow The Start Integration Workflow action initiates a configured workflow to enable data processing, transformation, or other tasks across connected systems. The Start Integration Workflow action is available on **Send Message Task**, **Task**, and **User Task** nodes within BPMN processes. ## Overview The Start Integration Workflow action allows a BPMN process to trigger an integration workflow, send input data, and receive the workflow output into process data through a Receive Message Task. This enables processes to delegate data fetching, transformations, and external system integrations to lightweight workflows without creating subprocesses. For triggering workflows from **UI Flows** (without a BPMN process), see the [Start Workflow action](../ui-flows#configuring-the-start-workflow-action). *** ## How it works When a Start Integration Workflow action is triggered: The input data mapped in the action configuration is sent as start variables to the workflow. The integration workflow runs with the provided inputs, executing its configured nodes (REST calls, data transformations, AI operations, etc.). Workflow output data is captured in the process instance upon completion, at the location configured on the Receive Message Task's Data Stream. The BPMN process continues to the next node after the workflow completes. The process waits for the workflow to complete before continuing. To receive output data, you must add a **Receive Message Task** node after the Send Message Task that triggers the workflow. *** ## Configuration ### Selecting a workflow The workflow search field (**Search workflow by name**) displays: * All workflows within the current app version * Any workflows referenced in the app (e.g., via the Library) ### Input mapping Map process variables to workflow input parameters: ```json theme={"dark"} { "customerId": "${processInstanceData.customer.id}", "requestType": "credit_check" } ``` ### Receiving output To capture workflow output in your process: 1. Add a **Receive Message Task** node after the node with the Start Integration Workflow action 2. In its **Data Stream** configuration, set the source to **Workflow** and select the workflow 3. Choose where the output lands: map each End node's output with **Output Mapping** (the default), or turn on **Legacy Mapping** and set a single **Key Name** 4. Subsequent nodes can access the output data at the mapped keys *** ## When to use | Scenario | Recommended Action | | - | - | | Call external APIs and return data | Start Integration Workflow | | Run data transformations | Start Integration Workflow | | Execute AI operations (extraction, generation) | Start Integration Workflow | | Multi-step user journeys | Use subprocesses instead | | Processes requiring state management | Use subprocesses instead | *** ## Related resources Tutorial: call a REST API from a workflow and start it from a process How node outputs land in process variables and how downstream nodes read them Build and configure integration workflows Trigger workflows from UI Flows without BPMN processes Learn about Send and Receive Message Task nodes Explore all available action types # Start new project instance Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-new-project-instance Initiate a new main process from within an ongoing process to handle isolated use cases across different apps or environments. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png) ### Key considerations * The "Start New Project Instance" action **cannot be configured as a subaction**. It must always be a standalone action. * This action is exclusively triggered **manually**; automated execution is not supported. You can launch a new project instance, which will always use the active version of the target application's build at the time of execution. *** ## Common use cases This action is particularly useful when multiple use cases are managed separately and require isolation between applications. For example: 1. **Customer Profile Management:** * Onboarding a power of attorney. * Submitting a mortgage request. * Enrolling in a credit card program. Each of these processes may be managed by different teams and applications, emphasizing the need for separation and flexibility. 2. **Cross-Application Workflow Initiation:** A process in one application might require triggering a process in another application with specific parameters. For instance: * Initiating an "Onboarding" process (version 2) for a customer directly from the main application. ## Configuring the action The **Start New Project Instance** action is configured via the **FlowX.AI Designer**. To set it up, navigate to the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node). ### Configuration options #### Action settings * **Name:** Used internally to distinguish actions on nodes. It’s recommended to define a naming standard for easier identification. * **Order:** If multiple actions exist on the same node, specify the order in which they run. * **Timer Expression:** Adds a delay to the action if needed. Use the [**ISO 8601 duration format**](https://www.w3.org/TR/NOTE-datetime) (e.g., `PT30S` for a 30-second delay). * **Action Type:** Must be set to **Start New Project Instance**. * **Trigger Type:** Always set to **Manual**. * **Required Type:** * **Mandatory:** Required for automatic actions. * **Optional or Mandatory:** Can be used for manual actions. * **Repeatable:** Check this box if the action can be triggered multiple times. * **Autorun Children:** Automatically runs child actions (mandatory and automatic) immediately after the parent action completes. * **Allow Back on This Action:** Enables users to move back in the process flow and redo previous actions. For details, see [Moving a Token Backwards in a Process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process). The "Start New Project Instance" action is incompatible with subprocess configurations because projects, unlike libraries, are self-contained collections of resources designed to satisfy specific use cases. Libraries provide reusable, lightweight resources and routines, such as error handling or enumerations, and do not manage complex business logic. #### Parameters The following parameters must be configured for the action: * **Project:** Specifies the target project to be initiated. * **Process:** Selects the process from the list of processes available in all builds. * **Start with Parameters:** Defines the parameters passed to the new process. These parameters can include: * **Customer Name:** Useful for initiating flows tailored to a specific customer. * **Copied Data:** Information from the current process that is required to start the target application’s process. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2013.36.55.png) *** ## Key benefits * **Isolated Process Management:** Supports launching new, isolated processes in separate applications, ensuring flexibility and independence across teams and environments. * **Active Version Execution:** Ensures that the project instance uses the active build version at the time of initiation, providing consistency in functionality. * **Parameter Passing:** Enables data transfer between the initiating and target processes, improving operational efficiency. # Start subprocess action Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-subprocess-action A Start subprocess action is an action that allows you to start a subprocess from another (parent) process. The "Start subprocess" is available only on [User Task](../node/user-task-node) nodes. For any other scenarios, you should use the [Call Activity node](../node/call-subprocess-tasks/call-activity-node) instead. Using **subprocesses** is a good way to split the complexity of your business flow into multiple, simple and reusable processes. Before configuring a Start subprocess action, read [Process design principles](../process/design-principles) for the rules on when to start a subprocess from a User Task action (must be optional, modal-only navigation) and how it differs from a Call Activity. ## Configuring a Start subprocess action To use a process as a [subprocess](../process/subprocess) you must first create it. Once the subprocess is created, you can start it from another (parent) process. To do this, you will need to add a **Start Subprocess** action to a [**User task**](../node/task-node) node in the parent process or by using a [Call activity node](../node/call-subprocess-tasks/call-activity-node). Here are the steps to start a subprocess from a parent process: 1. First, create a [process](../process/process-definition) designed to be used as a [subprocess](../process/subprocess). 2. In the parent process, create a **user task** node where you want to start the subprocess created at step 1. 3. Add a **Start subprocess** action to the task node. 4. Configure the **Start Subprocess** action and from the dropdown list choose the subprocess created at step 1. By following these steps, you can start a subprocess from a parent process and control its execution based on your specific use case. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/process_subprocess1.png) The following properties must be configured for a **Start subprocess** action: * [Action Edit](#action-edit) * [Trigger](#trigger) * [Execution](#execution) * [Navigation](#navigation) * [Select Subprocess](#select-subprocess) * [Subprocess Options](#subprocess-options) * [Data Mapping](#data-mapping) * [Advanced Configuration](#advanced-configuration) * [Data to send (for Manual actions)](#data-to-send) ### Action edit * **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions * **Action type** - should be set to **Start Subprocess** ### Trigger * **Manual** - toggle to choose if this action should be triggered manually (triggered by the user) or automatically (when the process flow reaches this step). In most use cases, this will be set to automatic * **Repeatable** - toggle to enable if the action can be triggered multiple times ### Execution * **Optional** - automatic actions are mandatory by default. Manual actions can be set as optional by enabling this toggle * **Autorun Children?** - when this is enabled, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized ### Navigation * **Allow back to this action** - enables back-in-process functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [**Moving a token backwards in a process**](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section ### Select Subprocess * **Subprocess name** - dropdown to select the process that you want to start as a subprocess. The dropdown displays the available subprocesses in the format `[Workspace]ProcessName` * **Branch** - a dropdown menu displaying available branches on the subprocess (both opened and merged) * **Version** - the type of version that should be used within the subprocess - **Latest Work in Progress**: * Displayed if the selected branch is not merged into another branch. * This configuration is used when there is a work-in-progress (WIP) version on the selected branch or when there is no WIP version on the selected branch due to either work in progress being submitted or the branch being merged. * In such cases, the latest available configuration on the selected branch is used. - **Latest Submitted Work**: * This configuration is used when there is submitted work on the selected branch, and the current branch has been submitted on another branch (latest submitted work on the selected branch is not the merged version). - **Custom Version**: * Displayed if the selected branch contains submitted versions. ### Subprocess Options * **Parallel Multi-Instance** - enables the subprocess to run multiple instances in parallel * **Start Async** - when enabled, the subprocess will start asynchronously ### Data Mapping * **Switch to legacy mapping** - toggle to enable legacy data mapping configuration When legacy mapping is enabled, you can configure: * **Copy from current state** - if a value is set here, it will overwrite the default behavior (of copying the whole data from the subprocess) with copying just the data that is specified (based on keys). Click the **+** button to add keys and specify the **Output Key** for each * **Exclude from current state** - specify which fields you want to exclude when copying the data from the parent process to the subprocess (by default all data fields are copied). Click the **+** button to add keys to exclude Map which data will be sent and received from the subprocess you are starting. ![Start Subprocess Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_subprocess_action_config.png) ### Advanced configuration * **Show Target Process** - toggle to enable the subprocess to communicate with the parent process (the process where this action is configured) ### Data to send * **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [**User task configuration**](../node/user-task-node) section) **Data to send** option is configurable only when the action **trigger type** is **Manual**. ## Example Let's create a main **process**, in this process we will add a user task node that will represent a menu page. In this newly added node we will add multiple subprocess actions that will represent menu items. When you select a menu item, a subprocess will run representing that particular menu item. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_menu1.png) To start a subprocess, we can, for example, create the following minimum configuration in a user task node (now we configure the process where we want to start a subprocess): * **Action** - `menu_item_1` - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions * **Trigger type** - Manual; Optional * **Repeatable** - yes * **Subprocess** - `docs_menu_item_1` - the name of the process that you want to start as a subprocess * **Exclude from current state** - `test.price` - copy all the data from the parent, except the price data * **Copy from current state** - leave this field empty to copy all the data (except the keys that are specified in the **Exclude from current state** field), if not, add the keys from which you wish to copy the data ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_example2.png) **Advanced configuration** * **Target process (parentProcessInstanceId)** - `${processInstanceId}` - current process ID #### Result ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/subprocess_example.gif) # Upload file action Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/upload-file-action An Upload File action is an action type that allows you to upload a file to a service available on Kafka. **Why is it useful?** The action will receive a file (or multiple files) from the frontend and send it to Kafka, and will also attach some metadata. The Upload File action supports two modes: Used with the [File Upload Button](../ui-designer/ui-component-types/buttons#file-upload-button). The SDK sends a single temp file ID (`{actionName}TempFileId`). Used with the [Multiple File Upload](../ui-designer/ui-component-types/multiple-file-upload) component. The SDK sends a list of temp file IDs (`{actionName}TempFileIds`). The process engine automatically detects which mode to use based on the parameter key present in the process instance data. ## Configuring an Upload file action Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure an Upload File action, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node), which has the following configuration options: * [Action Edit](#action-edit) * [Back in steps (for Manual actions)](#back-in-steps) * [Parameters](#parameters) * [Data to send (for Manual actions)](#data-to-send) * [UI Configuration](#ui-configuration) ### Action edit * **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions * **Order** - if multiple actions are defined on the same node, the running order should be set using this option * **Timer expression** - it can be used if a delay is required on that action. The format used for this is [ISO 8601 duration format ](https://www.w3.org/TR/NOTE-datetime)(for example, a delay of 30 seconds will be set up as `PT30S`) * **Action type** - should be set to **Upload File** * **Trigger type** (options are Automatic/Manual) - choose if this action should be triggered automatically (when the process flow reaches this step) or manually (triggered by the user); in most use cases, this will be set to automatic * **Required type** (options are Mandatory/Optional) - automatic actions can only be defined as mandatory. Manual actions can be defined as mandatory or optional. * **Repeatable** - should be checked if the action can be triggered multiple times * **Autorun Children** - when this is switched on, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized ![Upload File action Action Edit settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/01-upload_file_action_edit.png) ### Back in steps * **Allow BACK on this action** - back in process is a functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section. ### Parameters * **Topics** - the Kafka topic where the file will be posted * **Document Type** - other metadata that can be set (useful for the [document plugin](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview)) * **Folder** - allows you to configure a value by which the file will be identified in the future * **Advanced configuration (Show headers)** - this represents a JSON value that will be sent on the headers of the Kafka message ### Data to send * **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](../node/user-task-node) section) **Data to send** option is configurable only when the action **trigger type** is **Manual**. ## UI configuration When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality. ![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/10-ui_action_upload.png) *** ## Single vs. multi-file processing When the Upload File action executes, the process engine checks for two mutually exclusive parameter keys: | Key pattern | Type | Behavior | | - | - | - | | `{actionName}TempFileId` | `String` (single UUID) | **Single-file path** — sends a `DocumentPayload` to Kafka (existing behavior) | | `{actionName}TempFileIds` | `List` (UUID list) | **Multi-file path** — sends a `BulkDocumentPayload` to Kafka | If neither key is present, the action returns an error and no Kafka message is published. ### Multi-file Kafka topics When the multi-file path is triggered, the following dedicated Kafka topics are used: | Direction | Default topic | Description | | - | - | - | | Process engine → document plugin | `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Bulk persist request | | Document plugin → process engine | `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Per-file persist results | For multiple files, set the action's **Topics** parameter to the bulk persist topic. To read the results, add a Custom Topic data stream on the bulk results topic to the node. ### Multi-file request payload ```json theme={"dark"} { "documents": [ { "tempFileId": "550e8400-e29b-41d4-a716-446655440000", "customId": "119246", "documentType": "CONTRACT", "shouldOverride": false }, { "tempFileId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "customId": "119246", "documentType": "CONTRACT", "shouldOverride": false } ] } ``` `shouldOverride` is always `false` for multi-file uploads. All files share the same `customId` and use `documentType` from the action configuration (typically `BULK`). This means files accumulate — re-uploading adds new documents rather than replacing existing ones. ### Partial success handling The document plugin processes each file individually. If one file fails, the remaining files continue processing — successfully persisted files are not rolled back. The response includes a per-file status so your process logic can handle partial failures. ### Multi-file reply The bulk results message lists one entry per file under `documents`, each with its own `downloadPath`, `originalFileName`, and `error`: ```json theme={"dark"} { "documents": [ { "customId": "119246", "fileId": "8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10", "documentType": "BULK", "documentLabel": null, "minioPath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf", "filePath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf", "downloadPath": "internal/files/8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10/download", "originalFileName": "acme-brochure.pdf", "noOfPages": null, "error": null } ], "error": null } ``` `downloadPath` is relative and `filePath` is a storage path, not a URL. To show each uploaded file, see [Preview files in a collection](../ui-designer/ui-component-types/file-preview#preview-files-in-a-collection). ### Action order The process engine rejects an action while a mandatory action placed above it on the same node hasn't run. Place the Upload File action above any mandatory manual action, such as the `saveData` action a user task creates, by dragging it in the node's **Actions** list. *** ## Example: single file upload An example of **Upload File Action** is to send a file to the [document plugin](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview). In this case, the configuration will look like this: **Parameters configuration** * **Topics (topicName)** - will be set to the Documents plugin persist topic, by default `ai.flowx.plugin.document.trigger.persist.document.v1` * **Document Type** - metadata used by the document plugin, here we will set it to`BULK` * **Folder** - the value by which we want to identify this file in the future (here we use the **client.id** value available on the process instance data: `${application.client.id}` **Advanced configuration** * **Headers** - headers will send extra metadata to this topic -`{"processInstanceId": ${processInstanceId}, "destinationId": "currentNodeName"}`) ![Upload File action parameters with the persist topic, Document Type, and Folder set to the client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02-upload_file_action_params.png) ![Upload File action headers with processInstanceId and destinationId](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02b-upload_file_action_headers.png) The Documents plugin reply carries a relative `downloadPath`, not a complete URL. To show the uploaded file in a File Preview, see [Preview an uploaded file](../ui-designer/ui-component-types/file-preview#preview-an-uploaded-file). *** ## Academy courses Hands-on course covering data stream topics, upload actions, and file preview UI elements **Academy playground** — explore the [**uploadFilePreview**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/c0352c70-947e-4276-bd13-bb5cad2b547d/config/2457e456-2219-463c-af30-b92fe19c7703/processes) project for a working file upload and preview implementation. # Call activity node Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/call-activity-node The Call Activity node is a custom node type in the main process that provides advanced options for starting subprocesses. The call activity node runs another process as a subprocess inside the current one: in sync mode the parent waits for the subprocess to finish before advancing, while in async mode it continues without waiting. Use it to reuse a process across multiple parents or to split a large flow into manageable pieces. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/call_activity1.png) For when to use a Call Activity vs. starting a subprocess from a User Task action, mobile back-navigation behavior, and async mode constraints, see [Process design principles](../../process/design-principles). **Swimlane constraint**: a subprocess whose UI renders inside the parent process (through a **Parent Process** navigation area) must have **exactly one swimlane**. With multiple swimlanes, the runtime can't render the subprocess in the parent and reports `Could not render subprocess due to multiple swimlanes or missing Parent Process Area` - see the [error glossary](../../../resources/error-glossary#could-not-render-subprocess-due-to-multiple-swimlanes-or-missing-parent-process-area). The Call Activity node contains a default action for starting a subprocess, which can be started in two modes: * **Async mode**: The parent **process** will continue without waiting for the subprocess to finish. Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example, a task performed by an outside service. * **Sync mode**: The parent process must wait for the subprocess to finish before advancing. The start mode can be chosen when configuring the call activity. If the parent process needs to wait for the subprocess to finish and retrieve results, the parent process key that will hold the results must be defined using the *output key* node configuration value. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sync_async.png) ## Calling a subprocess from a library A Call Activity can start a process that belongs to a library, as long as the library is a dependency of your project. You configure it the same way as a subprocess from your own project: 1. Add the library to your project. See [Adding library dependencies](../../../projects/managing-applications/dependencies#adding-library-dependencies). 2. In the Call Activity's start subprocess action, open the process dropdown. Processes from your own project are listed under **Local**, and processes from each library are listed under the library's name. Select the library process. Only libraries already added as dependencies appear in the dropdown. You don't choose a library version in the Call Activity: the subprocess runs from the library version that your project's dependency points to. To use a newer version of the library process, [update the dependency](../../../projects/managing-applications/dependencies#updating-dependencies). ## Retrying the parent token Retrying the parent process token while it sits on a Call Activity node re-executes the node's start subprocess action, starting a **new subprocess instance**. The original subprocess instance isn't resumed or terminated: it remains in its current state alongside the new one. With [parallel multi-instance](#parallel-multi-instance) enabled, retrying the parent token starts a new full set of subprocess instances. Account for the extra instance when retrying: any work or data in the original subprocess instance is not carried over to the new one. ## Starting multiple subprocesses ### Parallel multi-instance The Call Activity node can also be used for starting a set of subprocesses that will be started and run at the same time. This is useful when there is an array of values in the parent process parameters, and a subprocess needs to be started for each element in that array. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/call_activity_parallel_multi_instance.png) #### Configuration options When configuring parallel multi-instance on a Call Activity node, you have access to the following configuration options: * **Input Array**: Declare the array used for subprocess input. Map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess. * **Output Array**: Declare the array used for subprocess output. Map from the subprocess object back to an array of objects in the parent process. * **Correlation attribute**: The attribute that will be used to correlate subprocess results with parent process data. #### Data mapping In the **Data Mapping** section, when **Parallel Multi-instance** is enabled, you can configure: ##### New data mapping 1. **Declare arrays**: Define the arrays used for subprocess input and subprocess output 2. **Input mapping**: In the mapping modal, map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess 3. **Output mapping**: Map from the subprocess object back to an array of objects in the parent process ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pmi_mapping.png) ##### Legacy mapping Legacy mapping works using current mechanics in both configuration and runtime, with no changes to existing features. When you change the arrays in the node configuration and save, any existing mappings for input and output will be automatically deleted. To filter, reshape, or compute over an array inside a mapping (instead of passing it through wholesale), switch the parameter to **function mode** with the **f(x)** icon and use JavaScript on the resolved value. See [Transforming arrays](../../process/data-mappers#transforming-arrays) on the Data mappers page for patterns and the `|| []` fallback. #### Correlation attribute behavior When results from parallel subprocesses are returned, the **correlation attribute** determines how the subprocess payload is handled: * **Update existing element**: When the correlation attribute value from the subprocess payload matches one or more elements in the parent process array, those elements are updated with the subprocess payload * **Insert new element**: When the correlation attribute value from the subprocess payload doesn't match any records in the parent process array, the payload is inserted as a new element in the array This allows for flexible data handling where subprocesses can either update existing records or add new ones based on the correlation logic. #### Output population and incomplete instances The output array in the parent process populates **incrementally**: each subprocess reports back as it completes, and the parent appends its result right away - results don't wait for the rest of the set. Results arrive in **completion order**, not input-array order; when a **correlation attribute** is configured, each result updates the element matching its correlation key instead of appending. Until the parent token advances, the accumulated values live in the parent's process data but aren't visible to subsequent nodes or the UI - you can confirm they arrived by inspecting the instance's process data in monitoring. In **Sync mode**, the parent token advances only when **every** instance in the set completes. A subprocess counts as completed when it **reaches an end node** or is **dismissed**. An instance that ends any other way (ABORTED, TERMINATED, EXPIRED, FAILED) never reports back to the parent, so the parent token keeps waiting - **there is no timeout on the wait** - even though the results of the completed instances are already present in the parent's process data. A partial run isn't recoverable: to get results for all items, run the operation again. Two configurations end the wait automatically: * **Expiry time on the parent process definition**: the parent (and, by default, its active subprocesses) moves to EXPIRED at the scheduled moment. The run isn't recovered, but it stops hanging. See [What happens when a process expires](../../process/process-definition#what-happens-when-a-process-expires). * **An interrupting boundary event (timer, message, or error) on the Call Activity node**: the parent advances on the boundary branch, and the still-active subprocess instances are aborted. Already-finished instances keep their FINISHED status. An instance reaches **ABORTED** in exactly two cases: an interrupting boundary event on the parent's Call Activity node (as above), or a token reset in the parent from a manual action with back-navigation, which aborts the subprocesses started by the actions being re-executed. For parallel multi-instance sets whose subprocesses depend on external systems (Kafka replies, integrations), configure an **interrupting boundary timer** on the Call Activity node so a single failed instance can't hold the parent indefinitely. The Retry action isn't available on an aborted subprocess instance, because Retry applies only to ACTIVE tokens. Retrying the parent token starts a new full set of subprocess instances — see [Retrying the parent token](#retrying-the-parent-token). #### Dismissing unfinished subprocesses When subprocesses are started in **Sync mode**: * If the token is advanced due to another action being performed in the process * Then the subprocesses that haven't finished are automatically dismissed This ensures that the parent process can continue without waiting indefinitely for subprocesses that may not complete. ### Business rule example Below is an example of an MVEL business rule used to generate a list of shipping codes: ```java theme={"dark"} import java.util.*; def mapValues(shippingCode) { return { "shippingCode": shippingCode } } shippingCodeList = []; shippingCodeList.add(mapValues("12456")); shippingCodeList.add(mapValues("146e3")); shippingCodeList.add(mapValues("24356")); shippingCodeList.add(mapValues("54356")); output.put("shippingCodeList", shippingCodeList); ``` In this example, the shippingCodeList array contains multiple shipping code maps. Each of these maps could represent parameters for individual subprocesses. The ability to generate and handle such arrays allows the system to dynamically start and manage multiple subprocesses based on the elements in the array, enabling parallel processing of tasks or operations. To achieve this, select the *parallel multi-instance* option. The *input array* name from the parent process also needs to be specified. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_array.png) When designing such a subprocess that will be started in a loop, remember that the input value for the subprocess (one of the values from the array in the parent process) will be stored in the subprocess parameter values under the key named *item*. This key should be used inside the subprocess. If this subprocess produces any results, they should be stored under a key named *result* to be sent back to the parent process. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_list.png) #### Subprocess business rule example Here's an MVEL business rule for a subprocess that processes shipping codes: ```java theme={"dark"} import java.util.*; map = new HashMap(); if (input.item.shippingCode.startsWith("1")) { map.package = "Fragile"; } else { map.package = "Non-fragile"; } map.shippingCode = input.item.shippingCode; output.put("result", map); ``` ## Result (one of the subprocess instances) The result shows the output of a process that has handled multiple shipping codes. The structure is: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_result.png) ```json theme={"dark"} { "package": "Non-fragile", "shippingCode": "54356" } ``` This contains the result of processing the specific shipping code, indicating additional attributes related to the shipping code (for example, package type) determined during the subprocess execution. # Start embedded subprocess Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/start-embedded-subprocess The Start Embedded Subprocess node initiates subprocesses within a parent process, allowing for encapsulated functionality and enhanced process management. ## Overview The Start Embedded Subprocess node enables the initiation of subprocesses within a parent process, offering a range of features and options for enhanced functionality. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/start_embedded_subprocess.png) ## Usage Considerations ### Data Management Embedded subprocesses offer advantages such as: * Segregated sections from a subprocess can be utilized without rendering them over the parent process. * Data is stored within the parent process instance, eliminating the need for data transfer. * Embedded subprocesses are visible in the navigation view. ### Runtime Considerations **Important** runtime considerations for embedded subprocesses include: * The **child process** must have only **one swimlane**. * Runtime swimlane permissions are inherited from the parent. * Certain boundary events are supported on Start Embedded Subprocess node, except for Timer events (currently not implemented). Embedded subprocesses cannot support multiple swimlanes in the actual implementation. ## Example Let's explore this scenario: Imagine you're creating a process that involves a series of steps, each akin to a sequential movement of a stepper. Now, among these steps, rather than configuring one step from scratch, you can integrate a pre-existing process, treating it as a self-contained unit within the overarching process. ### Step 1: Design the Embedded Subprocess Log in to the FlowX.AI Designer where you create and manage process flows. Start by creating a new process or selecting an existing process where you want to embed the subprocess. Design your navigation areas to match your needs. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/embedded_example_copy.png) Make sure you allocated all your user tasks into the navigation area accordingly. Within the selected process, design the subprocess by adding necessary tasks, events and so on. Ensure that the subprocess is contained within **a single swimlane**. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/subprocess_to_embed.png) To initiate a process with an embedded subprocess, designate the root Navigation Area of the subprocess as an inheritance placeholder **Parent Process Area** label in the **Navigation Areas**. Ensure that the navigation hierarchy within the Parent Process Area can be displayed beneath the parent navigation area within the main process interface. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/embed_sbprc.gif) Make sure you allocated all your user tasks into the navigation area accordingly. ### Step 2: Configure Start Embedded Subprocess Node Within the parent process, add a **Start Embedded Subprocess Node** from the node palette to initiate the embedded subprocess. Subprocess Nodes Configure the node to specify the embedded subprocess that it will initiate. This typically involves selecting the subprocess from the available subprocesses in your process repository. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/config_embed_node.png) ### Step 3: Customize Subprocess Behavior [**Alternative flows**](../../process/navigation-areas#alternative-flows) configured in the **main process** will also be applied to **embedded subprocesses** if they share the same name. Within the subprocess, handle data as needed. Remember that data is stored within the parent process instance when using embedded subprocesses. Implement boundary events within the subprocess if specific actions need to be triggered based on certain conditions. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/subprocess_instance.gif) ### Step 4: Test Integration Test the integration of the embedded subprocess within the parent process. Ensure that the subprocess initiates correctly and interacts with the parent process as expected. Verify that data flows correctly between the parent process and the embedded subprocess. Check if any results produced by the subprocess are correctly captured by the parent process. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/final_embed_result.gif) For further details on other ways of configuring and utilizing subprocesses, refer to the following resources: Subprocess lifecycle, Call Activity vs. User Task action, async constraints. # Error events Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/error-events Error Events expand the capabilities of process modeling and error handling within BPMN processing. These Error Event nodes enhance the BPMN standard and offer improved control over error management. Error events catch failures on a node so the process can take a recovery path instead of stopping. In FlowX.AI they attach to the boundary of an activity, a task, subprocess, or call activity, they always interrupt the activity they are attached to, and they fire when their configured condition is met. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_events.png) ## Intermediate event - error event (interrupting) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_event.png#center) ## Compatibility matrix for Error Events **Error Events** are used to handle error scenarios within BPMN processes. The following table outlines their compatibility with different node types: | **Node Type** | **Error Boundary Event** | | - | - | | **User Task** | Yes | | **Service Task** | Yes | | **Send Message Task** | Yes | | **Receive Message Task** | Yes | | **Subprocess** | Yes | | **Call Activity** | Yes | ## Key characteristics 1. **Boundary of an Activity node or Subprocess:** * Error Events can only be used on the boundary of an activity, including subprocesses nodes. They cannot be placed in the normal flow of the process. 2. **Always Interrupt the Activity:** * It's important to note that Error Events always interrupt the activity to which they are attached. There is no non-interrupting version of Error Events. 3. **Handling Thrown Errors:** * A thrown error, represented by an Error Event, can be caught by an Error Catch Event. This is achieved specifically using an Error Boundary Event, which is placed on the boundary of the corresponding activity. 4. **Using error events on Subprocesses nodes**: * An error catch event can be linked to a subprocess, with the error source residing within the subprocess itself, denoted by the presence of an error end event, signifying an abnormal termination of the subprocess. ## Configuring an Error Intermediate boundary event ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_scenario.png) * **Name**: Assign a name to the event for easy identification. * **Condition**: Specify the condition that triggers the error event. Various script languages can be used for defining conditions, including: * MVEL * JavaScript * Python To draw a sequence from an error event node and link it to other nodes, follow these steps: right-click on the node, and then select the option to "Add Sequence." When crafting a condition, use a predefined key as illustrated below: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/scenario_input.gif) For instance, in the example provided, we've taken a process key defined on a switch UI element and constructed a user-defined condition like this: `input.application.switch == true`. * **Priority**: Determine the priority level of this error event in relation to other error events added on the same node. When multiple error events are configured for a node, and multiple conditions simultaneously evaluate to true, only one condition can interrupt the ongoing activity and advance the token to the next node. The determination of which condition takes precedence is based on the "priority" field. If the "priority" field is set to "null," the system will randomly select one of the active conditions to trigger the interruption. * `input.application.switch`: This represents a key to bind a value to the Switch UI element within the "application" part of the "input". It is used in this example to capture input or configuration from a user. * `==`: This is an equality operator, and it checks if the value on the left is equal to the value on the right. * `true` is a boolean value, which typically represents a state of "true" or "on." So, when you put it all together, the statement is checking if the value of the "input.application.switch" is equal to the string "true." If the value of "input.application.switch" is indeed "true" (as a string), the condition is considered true. If the value is anything other than "true," the condition is false and the error is triggered. ### Use case: handling errors during User Task execution **Description:** This use case pertains to a page dedicated to collecting client contact data. Specifically, it deals with scenarios where users are given the opportunity to verify their email addresses and phone numbers. In this scenario we will create a process to throw an error if an email address is not valid. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_execution.png) #### Example configuration 1. **Error Boundary Event:** We will set an error boundary event associated with a user task. 2. **Error Node:** The node will be responsible to redirect the user to other flows after the user's email address is validated based on the conditions defined. ```java theme={"dark"} input.application.client.contactData.email.emailAddress != "john.doe@email.com" ``` The expression checks if the email address configured in `application.client.contactData.email.emailAddress` key is not equal to "[john.doe@email.com](mailto:john.doe@email.com)." If they are not the same, it evaluates to true, indicating a mismatch. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_val_v1.png) 3. **Flow Control:** Depending on the outcome of the validation process, users will be directed to different flows, which may involve displaying error modals as appropriate. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_email.gif) *** ## Academy courses Learn exception handling, process/token status, error types, and debugging patterns **Academy playground** — explore the [**Academy\_Throw\_catch**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/489ac77b-3ba0-444a-b9c8-2a5ffee26492/config/83a4647b-619d-4ddc-87cf-e04d03b6e1d2/processes) and [**errorMessage**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/870d5a68-d770-44b1-a428-4dafa4c361d3/config/c77f6db9-4e30-4f4c-bfab-3ee22e265e5d/processes) projects for working examples of error handling patterns. # Exclusive gateway Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/exclusive-gateway-node In the world of process flows, decisions play a crucial role, and that's where the Exclusive Gateway comes into play. This tool enables you to create conditional pathways based on data provided. ## Understanding Exclusive (XOR) Gateway An exclusive gateway (also called XOR gateway) represents a decision point in your process where exactly one outgoing path is selected based on conditions. This is one of the most common routing mechanisms used in business process modeling. **Core principles of Exclusive Gateways** When designing decision logic with exclusive gateways, consider these guiding principles: An exclusive gateway evaluates multiple conditions, but only **one outgoing sequence flow** will be taken - the first condition that evaluates to *true*. Each outgoing path from an XOR gateway depends on a condition that evaluates to *true* or *false*. Overlapping conditions - where multiple paths could match - can lead to **unpredictable routing**. Gateways will select the first matching path, which might not be the correct one. This is the essential question behind every XOR gateway: **"Given the input, which path should the process follow?"** Before deploying a process with an XOR gateway, test it using **realistic data sets** and **edge cases**. Ensure each possible path behaves as expected - and none are silently skipped or broken. Every XOR gateway introduces a **decision point**. Each outgoing sequence flow represents a **distinct outcome** - make sure those outcomes are meaningful and necessary. Include a **default path** in the gateway to catch any scenario where none of the defined conditions match. This is especially important when the decision logic depends on external or dynamic data. Your conditions should be **simple, explicit, and named clearly**. Avoid nesting complex expressions directly in the gateway when possible - move logic to a service task if needed. Business rules change. Processes evolve. If your gateway logic doesn't keep up, the process will drift out of sync with how the business actually works. ## Configuring an Exclusive Gateway node ![Exclusive gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive.png#center) To configure this node effectively, it's essential to set up both the **input** and **output** sequences within the gateway process. ![Exclusive Gateways single](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_single.png) ![Exclusive Gateways multiple](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple.png) ### General configuration * **Node name**: Give your node a meaningful name. * **Can go back**: Enabling this option allows users to revisit this step after completing it. When a step has "Can Go Back" set to false, all preceding steps become inaccessible. * [**Stage** ](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node. ![Exclusive gateway configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/excl_gtway.png) ### Gateway decisions * **Language**: When configuring conditions, you can use JavaScript, Python, MVEL, or Groovy expressions that evaluate to either **true** or **false**. * **Conditions**: In the **Gateway Decisions** tab, you can see that the conditions (**if, else if, else**) are already built-in and you can **select** the destination node when the condition is **true**. The order of expressions matters; the first **true** evaluation stops execution, and the token moves to the selected node. ![Exclusive Gateways Decisions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_gateway_decisions.png) After the exclusive portion of the process, where one path is chosen over another, you'll need to either end each path (as in the example below) or reunite them into a single process (as in the example above) using a new exclusive gateway without any specific configuration. ![Exclusive Gateways Multiple Flows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple_flows.png) ## JavaScript examples ### Getting input from a Switch UI element Let's consider the following example: we want to create a process that displays 2 screens and one modal. The gateway will direct the token down a path based on whether a switch element (in our case, VAT) is toggled to true or false. ![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_config_example.png) If, during the second screen, the VAT switch is toggled on, the token will follow the second path, displaying a modal. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/vat_on.gif) After interacting with the modal, the token will return to the main path, and the process will continue its primary flow. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_flow.png) **Example configuration**: * **Language**: JavaScript * **Expression**: ```javascript theme={"dark"} input.application.company.vat == true // you can use the same method to access a value for other supported scripts in our platform: MVEL, Python and Groovy ``` Essentially, you are accessing a specific value or property within a structured data object. The format is usually `input.{{key from where you want to access a value}}`. In simpler terms, it's a way to verify if a particular property within your input data structure (`input.application.company.vat` key attached to Switch UI element) is set to the value true. If it is, the condition is met and returns true; otherwise, it returns false. The `application.company.vat` key corresponds to the switch UI element. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/VAT_key.png) ### Getting input from multiple UI elements Consider another scenario in which the process relies on user-provided information, such as age and membership status, to determine eligibility for a discount. This decision-making process utilizes multiple conditions, and depending on the input, it may either conclude or continue with other flows. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_example_discount.gif) **Configuration example**: ![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_config_example.png) In our case, the expressions fields will be populated with the `input.application.client.age` and `input.application.client.membership` keys, which correspond to the user input collected on the initial screen. Here's how we've configured the rules for our discount eligibility process: 1. Users under 18 with standard membership are not eligible (redirected to not\_eligible\_modal): ``` input.application.client.age < 18 && input.application.client.membership == "standard" ``` 2. Users 18 or older with standard membership are not eligible due to membership level (redirected to not\_eligible\_membership): ``` input.application.client.age >= 18 && input.application.client.membership == "standard" ``` 3. Users 18 or older with gold membership qualify for a discount (redirected to discount\_applied): ``` input.application.client.age >= 18 && input.application.client.membership == "gold" ``` 4. Users 18 or older with platinum membership also qualify for a discount (redirected to discount\_applied): ``` input.application.client.age >= 18 && input.application.client.membership == "platinum" ``` 5. Any other combinations are sent to needsValidation for further review. Each rule uses the logical AND operator (&&) to ensure both conditions must be true for the rule to apply. The rules are evaluated in sequence, and the process follows the path of the first matching rule. The process is visualized as follows: