# Node actions Source: https://docs.flowx.ai/5.1/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 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#message-send-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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/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-message-send-task-node)). 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/callback2.png) #### Example Add callback actions in the **Advanced configuration** tab, in the **header** parameter `callbacksForAction`. ```js theme={"system"} {"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. # Append params to parent process Source: https://docs.flowx.ai/5.1/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. ## 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) * [Back in steps (for Manual actions)](#back-in-steps) * [Parameters](#parameters) * [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 * **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 **Append Params to Parent Process** * **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 ### 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 * **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 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. **Advanced configuration** * **Show Target Process** - ID of the parent process where you need to copy the params, this was made available on to the `${parentProcessInstanceId}` variable, if you defined it when you [started the subprocess](./start-subprocess-action) ### 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 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** - `{"client": ${data.client.age}}` to copy the age of the client (the param value we want to copy) * **Destination in the parent state** - `application` to append the data o to the **application** key on the parent process **Advanced configuration** * **Show Target Process** - `${parentProcessInstanceId}`to copy the data on the parent of this subprocess ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/append_params_example.png) # Business rules types Source: https://docs.flowx.ai/5.1/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#action-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. 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={"system"} { "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={"system"} 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={"system"} { "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={"system"} 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={"system"} 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={"system"} 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={"system"} 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.1/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. 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 a process. ### Retrieve security details Use the following business rule to fetch and store security details: ```JavaScript theme={"system"} // 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={"system"} { "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": {} } } } } } ``` ### 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={"system"} // 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={"system"} # 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={"system"} // 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={"system"} { "email": "user@email.com", "username": "user@email.com", "firstName": "John", "lastName": "Snow" } ``` *** ## 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={"system"} // 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={"system"} // 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.1/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. * [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** - Always set to Automatic. The Kafka Send Action type is always **Automatic**. Typically, Kafka Send Actions automatically trigger when the process reaches this step. * **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/core-extensions/integration-management/). * **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 seamless communication across various systems and plugins, enabling efficient data transfer, robust 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-flowxai-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-flowxai-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) validation - Refer to this [example](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification). * 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.1/docs/building-blocks/actions/send-data-to-user-interface Send data to user interface action is based on Server-Sent Events (SSE), a web technology that enables servers to push real-time updates or events to clients over a single, long-lived HTTP connection. It provides a unidirectional communication channel from the server to the client, allowing the server to send updates to the client without the need for the client to continuously make requests. **Why is it useful?** It provides real-time updates and communication between the **process** and the frontend application. ## 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) * [Back in steps (for Manual actions)](#back-in-steps) * [Parameters](#parameters) * [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 * **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 Send data to user interface * **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 ### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/websocket_action_edit.png) ### Parameters The following fields are required for a minimum configuration of this type of action: * **Message Type** - if you only want to send data, you can set this to **Default** (it defaults to the **data** message type) If you need to start a new process using a **Send data to user interface**, you can do that by setting the **Message Type** to **Action** and you will need to define a **Message** with the following format: ```json theme={"system"} { "processName": "demoProcess", "type": "START_PROCESS_INHERIT", "clientDataKeys":["webAppKeys"], "params": { "startCondition": "${startCondition}", "paramsToCopy": [] } } ``` * `paramsToCopy` - choose which of the keys from the parent process parameters to be copied to the subprocess * `withoutParams` - choose which of the keys from the parent process parameters are to be ignored when copying parameter values from the parent process to the subprocess * **Message** - here you define the data to be sent as a JSON object, you can use constant values and values from the process instance data. * **Target Process** - is used to specify to what running process instance should this message be sent - **Active process** or **Parent process** If you are defining this action on a [**Call activity node**](../node/call-subprocess-tasks/call-activity-node), you can send the message to the parent process using **Target Process: 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** option is configurable only when the action **trigger type** is **Manual**. ![](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**. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/websocket_send_update_data.gif) # Start integration workflow action Source: https://docs.flowx.ai/5.1/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 allows for data transfer by sending configured inputs to initiate workflows and receiving outputs at the designated result key once the workflow completes. Here’s an overview of its key functionalities: ### Triggering When a Start integration workflow action is triggered: * The input data mapped in Input is sent as start variables to the workflow. * The workflow runs with these inputs. * Workflow output data is captured on the the specified result key upon completion. ### Integratiom mapping The Select Workflows dropdown displays: * All workflows within the current application version. * Any workflows referenced in the application (e.g., via the Library). ### Workflow output To receive output data from a workflow: * Add a Receive Message Task node to the BPMN process. * This node ensures that output data is properly captured and processed based on the designated workflow configuration. # Start new project instance Source: https://docs.flowx.ai/5.1/docs/building-blocks/actions/start-new-project-instance The Start New Project Instance action allows users to initiate a completely new process (referred to as a "main process") from within an ongoing process. This functionality is designed to support scenarios where isolated use cases are managed across different applications 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 seamless data transfer between the initiating and target processes, improving operational efficiency. # Start subprocess action Source: https://docs.flowx.ai/5.1/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. ## 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 in order 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.1/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 from the frontend and send it to Kafka, and will also attach some metadata. ## 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 ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/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 * **Address** - 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/notifications-plugin/sending-a-notification)) * **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 UI action that corresponds to the Upload File node action, you must set the **UI action type** to **upload**. This ensures proper integration between the frontend interface and the backend upload functionality. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_action_upload.png) ## Example An example of **Upload File Action** is to send a file to the [document plugin](../../../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification). In this case, the configuration will look like this: **Parameters configuration** * **Address (topicName)** - will be set to (the id of the document plugin service) `ai.flowx.in.document.persist.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"}`) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/upload_file_action_params.png) # Call activity node Source: https://docs.flowx.ai/5.1/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. There are cases when extra configuration is needed on certain nodes to enhance process management and execution. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/call_activity1.png) 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) ## 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. #### 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. #### 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={"system"} 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={"system"} 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={"system"} { "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.1/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 seamlessly 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: # Error events Source: https://docs.flowx.ai/5.1/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. ![](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, simply 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={"system"} 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) # Exclusive gateway Source: https://docs.flowx.ai/5.1/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 powerful 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={"system"} 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: