# Node actions Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/actions/actions The activity that a node has to handle is defined using an action. These can have various types, they can be used to specify the communication details for plugins or integrations. Node actions allow you to incorporate **business rules** into a **process**, and send various data to be displayed in front-end applications. 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 can use action rules such as DMN rules, MVEL expressions, or scripts in JavaScript, Python, or Groovy to attach business rules to a node. For more information about supported scripting languages, click on this card. Each button on the user interface corresponds to a manual user action. ### Action edit Actions can be: * Manual or automatic * Optional or mandatory If all the mandatory actions are not executed on a node, the flow (token) will not advance. * Actions can also be marked as one-time or repeatable ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/actns_ovrvw.png) ### Action parameters Action params store extra values as key/value pairs, like topics for outgoing messages or message formats for the front-end. A decision on an **exclusive gateway** is defined using a **node rule**. Similar to action rules, these can be set using [DMN](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-dmn) or [MVEL](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-mvel). ## Configuring actions Actions have a few characteristics that need to be set: * an **action** can be set as **manual** or **automatic**. Manual actions can be executed only through the REST API, this usually means they are triggered by the application user from the interface. Automatic actions are executed without any need for external triggers. * manual actions can be either mandatory or optional. Automatic actions are all considered mandatory. * all actions have an **order.** When there are more actions on a single node, the order needs to be set. * **repeatable** - the actions that could be triggered more than once are marked accordingly * the actions can have a parent/child hierarchy * **allow back to this action** - the user can navigate back to this action from a subsequent node For more information, check the following section: ## Linking actions together There are two ways actions could be linked together, so certain actions can be set to 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 a specific message is received by the Engine, 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 this flag is set to `true`, the child actions (the ones defined as mandatory and automatic) will be run immediately after the execution of the parent action is finalized. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/autorun_children.png) ### Callback actions Child actions can be marked as callbacks to be run after a reply from an external system is received. They will need to be set 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, a callback function might be used to handle a user's interaction with a web page, such as upload a file. When the user performs the action, the callback function is executed, allowing the web application to respond appropriately. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/callback1.png) Child actions can be marked as callbacks to be run after a reply from an external system is received. They will need to be set when defining the interaction with the external system (the Kafka send action). ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/callback2.png) #### Example Callback actions are added in the **Advanced configuration** tab, in the **header** param - `callbacksForAction`. ```js {"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 this callback will be called once the "upload\_file" action is completed. ## Scheduling actions A useful feature for actions is having the ability to set them to run at a future time. Actions can be configured to be run after a period of time, starting from the moment the token triggered them to be executed. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/scheduled_actions.png) # Append params to parent process Source: https://docs.flowx.ai/4.6.0/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-process-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/4.6.0/docs/building-blocks/actions/business-rule-action/business-rule-action A business rule is an action type in FlowX 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 [DMN rules](./dmn-business-rule-action), [MVEL](../../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-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 { "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 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 { "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 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 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 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 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']] } ``` For more detailed information on each type of Business Rule Action, refer to the following sections: [DMN Business Rule Action](./dmn-business-rule-action) # Configuring a DMN business rule action Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/actions/business-rule-action/dmn-business-rule-action Decision Model and Notation is a graphical language used to specify business decisions. DMN helps convert complex decision-making code into easily readable diagrams. ## Creating a DMN Business Rule action To create and link a DMN **business rule** action to a task **node** in FLOWX, follow these steps: 1. Launch **FlowX Designer** and navigate to **Process Definitions** . 2. Locate and select your specific process from the list, then click on **Edit Process**. 3. Choose a **task node**, and click the **Edit** button (represented by a key icon). This action will open the node configuration menu. 4. Inside the node configuration menu, head to the **Actions** tab and click the "**+**" button to add a new action. 5. From the dropdown menu, select the action type as **Business Rule**. 6. In the **Language** dropdown menu, pick **DMN**. For a visual guide, refer to the following recording: ![Creating a DMN Business Rule Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/create_dmn_business_rule_action.gif) ## Using a DMN Business Rule Action Consider a scenario where a bank needs to perform client information tasks/actions to send salutations, similar to what was previously created using MVEL [here](./business-rule-action#business-rules-examples). A business person or specialist can use DMN to design this business rule, without having to delve into technical definitions. Here is an example of an **MVEL** script defined as a business rule action inside a **Service Task** node: ```java 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" } }); } ``` The previous example can be easily transformed into a DMN Business Rule action represented by the decision table: ![DMN Decision Table](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_decision_ex.png) In the example above, we used FEEL expression language to write the rules that should be met for the output to occur. FEEL defines a syntax for expressing conditions that input data should be evaluated against. **Input** - In the example above, we used the user-selected gender from the first screen as input, bound to the `application.client.gender` key. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_screen.png) **Output** - In the example above, we used the salutation (bound to `application.client.salutation`) computed based on the user's gender selection. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_salutation.png) DMN also defines an XML schema that allows DMN models to be used across multiple DMN authoring platforms. The following output is the XML source of the decision table example from the previous section: ```xml application.client.gender "M" "Mr" "F" "Ms" "O" "Mx" ``` # Kafka send action Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/actions/kafka-send-action The FlowX 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) ## 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/plugins/custom-plugins/documents-plugin/documents-plugin-overview). * Updating/deleting documents - Find an example [here](../../platform-deep-dive/plugins/custom-plugins/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/plugins/custom-plugins/notifications-plugin/sending-a-notification) and emails with attachments [here](../../platform-deep-dive/plugins/custom-plugins/notifications-plugin/sending-an-email-with-attachments). * One-Time Password (OTP) validation - Refer to this [example](../../platform-deep-dive/plugins/custom-plugins/notifications-plugin/sending-a-notification). * Forwarding notifications to external systems - Explore this [example](../../platform-deep-dive/plugins/custom-plugins/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 or using hooks. Find examples [here](../../flowx-designer/managing-a-process-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/4.6.0/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 Designer**. To configure a Send data to user interface, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-process-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-process-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 { "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/4.6.0/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/4.6.0/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 Designer**. To set it up, navigate to the **Actions** tab at the [task node level](../../flowx-designer/managing-a-process-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-process-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/4.6.0/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. 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) * [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 **Start Subprocess** * **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-process-flow/moving-a-token-backwards-in-a-process) section. ### Parameters * **Subprocess name** - the name of the process that you want to start as a subprocess * **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. * **Custom version** - displayed if the selected branch contains submitted versions * **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) * **Exclude from current state** - what fields do you want to exclude when copying the data from the parent process to the subprocess (by default all data fields are copied) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_version.png) **Advanced configuration** * **Show Target Process** - ID of the current process, to allow the subprocess to communicate with the parent process (which is 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/4.6.0/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 Designer**. To configure an Upload File action, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-process-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) ### 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-process-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/plugins/custom-plugins/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**. ## Example An example of **Upload File Action** is to send a file to the [document plugin](../../platform-deep-dive/plugins/custom-plugins/documents-plugin/documents-plugin-overview). 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": "curentNodeName"}`) ![](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/4.6.0/docs/building-blocks/node/call-subprocess-tasks/call-activity-node Call activity is a node that provides advanced options for starting subprocesses. There are cases when extra functionality 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/release40/ca_output_key.png) ## Starting multiple subprocesses This node type 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/release40/ca_parent_array.png) #### Business rule example Below is an example of an MVEL business rule used to generate a list of shipping codes: ```java 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 *collection key* name from the parent process also needs to be specified. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ca_collection.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/release40/ca_subprocess.png) #### Subprocess business rule example Here's an MVEL business rule for a subprocess that processes shipping codes: ```java 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/release40/ca_result.png) ```json { "package": "Non-fragile", "shippingCode": "54356" } ``` This contains the result of processing the specific shipping code, indicating additional attributes related to the shipping code (e.g., package type) determined during the subprocess execution. # Start embedded subprocess Source: https://docs.flowx.ai/4.6.0/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 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/4.6.0/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 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/4.6.0/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 with ease. ## 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/gateway_exclusive_diagram.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. * [**Swimlane**](../../platform-deep-dive/user-roles-management/swimlanes): Choose a swimlane, ensuring that specific user roles have access only to certain process nodes. If there are no multiple swimlanes, the value is **Default**. * [**Stage** ](../../platform-deep-dive/plugins/custom-plugins/task-management/using-stages): Assign a stage to the node. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive_stages.png) ### Gateway decisions * **Language**: When configuring conditions, you can use [MVEL](/4.0/docs/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-mvel) (or [DMN](#dmn-example)) 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/gateway_rule.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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/end_other_FLOW.png) ## MVEL example ### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/vat_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/release34/process_run_xor.png) #### Example configuration * **Language**: MVEL * **Expression**: ```java input.application.company.vat == true // you can use the same method to access a value for other supported scripts in our platform: JavaScript, 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. To ensure that the stored data can be accessed by the `.input method`, add a "Data to send" action on the node where you define your keys and your UI. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/config_example_xor.png) 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) ## DMN example If you prefer to use [DMN](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-dmn) to define your gateway decisions, you can do so using exclusive gateways. ![Gateway Decisions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_gif.gif) ### Getting input from a Switch UI element **Gateway Decision - DMN example** [(Applicable only for Exclusive Gateway - XOR)](./exclusive-gateway-node) ![Gateway Decision](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/xor_dmn_decision.png) #### Configuration example * **Language**: DMN * **Expression**: `application.company.vat` In our case, the expression field will be filled in with `application.company.vat` key, which corresponds to the switch UI element. * **Hit Policy**: Unique * **Type**: Boolean * **Next Node name**: Enter the name of the nodes to which you prefer the token to be directed. ### 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 a DMN (Decision Model and Notation) decision table, and depending on the input, it may either conclude or continue with other flows. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_input.gif) #### Configuration example ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_multiple_UI_elements.png) In our case, the expressions fields will be populated with the `application.company.vat` and `application.client.membership` keys, which correspond to the user input collected on the initial screen. The process is visualized as follows: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dmn_example.gif) # Message catch boundary events Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-catch-boundary-event Boundary events are integral components linked to user tasks within a process flow. Specifically, Message Catch Boundary Events are triggered by incoming messages and can be configured as either interrupting or non-interrupting based on your requirements. **Why is it important?** It empowers processes to actively listen for and capture designated messages during the execution of associated user tasks. When an event is received, it progresses through the sequence from the intermediate **node**. Multiple intermediate boundary events can exist on the same user task, but only one can be activated at a time. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_boundary_multiple.png) Message Catch Boundary Events can be categorized by their behavior, resulting in two main classifications: * [**Interrupting**](#message-catch-interrupting-event) * [**Non-interrupting**](#message-catch-non-interrupting-event) ## Message catch interrupting event ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_interrupting_event.png#center) In the case of an Interrupting Message Catch Boundary Event triggered by a received message, it immediately interrupts the ongoing task. The associated task concludes, and the **process flow** advances based on the received message. * **Use Cases:** * Suitable for scenarios where the receipt of a specific message requires an immediate interruption of the current activity. * Often used when the received message signifies a critical event that demands prompt attention. * **Example:** * A user task is interrupted as soon as a high-priority message is received, and the process flow moves forward to handle the critical event. ## Message catch non-interrupting event ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/%20message_catch_non_interrupting.png#center) Contrastingly, a Non-Interrupting Message Catch Boundary Event continues to listen for messages during the execution of the associated task without immediate interruption. The task persists in its execution even upon receiving messages. Multiple non-interrupting events can be activated concurrently while the task is still active, allowing the task to continue until its natural completion. * **Use Cases:** * Appropriate for scenarios where multiple messages need to be captured during the execution of a user task without disrupting its flow. * Useful when the received messages are important but do not require an immediate interruption of the ongoing activity. * **Example:** * A user task continues its execution while simultaneously capturing and processing non-critical messages. ## Compatibility matrix for Message Events **Message Events** can be used in various contexts within BPMN processes. The following table outlines their compatibility with the following nodes: | **Node Type** | **Message Catch Event - Interrupting** | **Message Catch Event - Non-Interrupting** | | ----------------------------- | -------------------------------------- | ------------------------------------------ | | **User Task** | Yes | Yes | | **Service Task** | Yes | Yes | | **Send Message Task** | No | No | | **Receive Message Task** | Yes | Yes | | **Start Embedded Subprocess** | Yes | Yes | | **Call Activity** | Yes | Yes | ## Configuring a message catch interrupting/non-interrupting event #### General config * **Correlate with Throwing Events** - the dropdown lists all throw events from accessible process definitions Establishes correlation between the catch event and the corresponding throw event. Selection of the relevant throw event triggers the catch event upon message propagation. * **Correlation Key** - process key used to correlate received messages with specific process instances The correlation key associates incoming messages with specific process instances. Upon receiving a message with a matching correlation key, the catch event is triggered. * **Receive Data (Process Key)** - the catch event can receive and store data associated with the message in a process variable with the specified process key This received data becomes available within the process instance, facilitating further processing or decision-making. ## Illustrating boundary events (interrupting and non-interrupting) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/boundary_multiple.png) **Business Scenario:** A customer initiates the account opening process. Identity verification occurs, and after successful verification, a message is thrown to signal that the account is ready for activation. Simultaneously, the account activation process begins. If there are issues during activation, they are handled through the interruption process. The overall process ensures a streamlined account opening experience while handling potential interruptions during activation, and also addresses exceptions through the third lane. # Message catch start event Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-catch-start-event Message Catch Start Event node represents the starting point for a process instance based on the receipt of a specific message. When this event is triggered by receiving the designated message, it initiates the execution of the associated process. **Why it is important?** The Message Catch Start Event is important because it allows a process to be triggered and initiated based on the reception of a specific message. ## Configuring a message catch start event A Message Catch Start Event is a special event in a process that initiates the start of a process instance upon receiving a specific message. It acts as the trigger for the process, waiting for the designated message to arrive. Once the message is received, the process instance is created and begins its execution, following the defined process flow from that point onwards. The Message Catch Start Event serves as the entry point for the process, enabling it to start based on the occurrence of the expected message. It is mandatory that in order to use this type of node together with task management plugin, to have a service account defined in your identity solution. For more information, check our documentation in how to create service accounts using Keycloak, [**here**](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account). ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_catch_message_event.png#center) #### General config * **Can go back?** - setting this to true will allow users to return to this step after completing it, when encountering a step with `canGoBack` false, all steps found behind it will become unavailable * **Correlate with catch events** - the dropdown contains all catch messages from the process definitions accessible to the user * **Correlation key** - is a process key that uniquely identifies the instance to which the message is sent * **Send data** - allows the user to define a JSON structure with the data to be sent along with the message * **Stage** - assign a stage to the node, if needed ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_start_config.png) ## Interprocess communication with throw and message catch start events ### Throw process ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_for_start.png) #### Configuring the throw intermediate event ##### General config * **Can go back?** - Setting this to true allows users to return to this step after completion. When encountering a step with canGoBack set to false, all steps found behind it become unavailable. * **Correlate with catch events** - Should match the configuration in the message catch start event. * **Correlation key** - A process key that uniquely identifies the instance to which the message is sent. * **Send data** - Define a JSON structure with the data to be sent along with the message. In our example, we will send a test object: ```json {"test": "docs"} ``` * **Stage** - Assign a stage to the node if needed. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_for_start_config.png) ### Start with catch process ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_catch_message_proc.png) #### Configuring the message catch start event Remember, it's mandatory to have a service account defined in your identity solution to have the necessary rights to start a process using the message catch start event. Refer to our documentation on how to create service accounts using Keycloak, [**here**](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account). ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_start_event_config.png) After running the throw process, the process containing the start catch message event will be triggered. The data is also sent: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_catch_event_response.png) # Message Events Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-events Message events serve as a means to incorporate messaging capabilities into business process modeling. These events are specifically designed to capture the interaction between different process participants by referencing messages. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_events_new.png) By leveraging message events, processes can pause their execution until the expected messages are received, enabling effective coordination and communication between various system components. ## Intermediate events | Trigger | Description | Marker | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Message | A Message Intermediate Event serves to send or receive messages. A filled marker denotes a "throw" event, while an unfilled marker indicates a "catch" event. This either advances the process or alters the flow for exception handling. Identifying the Participant is done by connecting the Event to a Participant through a Message Flow. | Throw ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/throw_message_event.png#center) Catch ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_intermediate_event.png#center) | ## Boundary events Boundary Events involve handling by first consuming the event occurrence. Message Catch Boundary Events, triggered by incoming messages, can be configured as either interrupting or non-interrupting. | Trigger | Description | Marker | | ------- | ------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------: | | Message | **Non-interrupting Message Catch Event**: The event can be triggered at any time while the associated task is being performed. | Non-interrupting ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/%20message_catch_non_interrupting.png#center) | | Trigger | Description | Marker | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------: | | Message | **Interrupting Message Catch Event**: The event can be triggered at any time while the associated task is being performed, interrupting the task. | Interrupting ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_interrupting_event.png#center) | ## Intermediate vs boundary **Intermediate Events** * Intermediate events temporarily halt the process instance, awaiting a message. **Boundary Interrupting Events** * These events can only be triggered while the token is active within the parent node. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/token_interrupting.png) * Upon activation, the parent node concludes, and the token progresses based on the boundary flow. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/token_intterrupting_exec.png) **Boundary Non-Interrupting Events** * Similar to interrupting events, non-interrupting events can only be triggered while the token is active in the parent node. * Upon triggering, the parent node remains active, and a new token is generated to execute the boundary flow concurrently. FLOWX.AI works with the following message events nodes: * [**Message catch start event**](./message-catch-start-event) * [**Message intermediate events**](./message-intermediate/) * [**Message catch boundary event**](./message-catch-boundary-event) ## Message events correlation Messages are not sent directly to process instances. Instead, message correlation is achieved through message subscriptions, which consist of the message name and the correlation key (also referred to as the correlation value). A correlation key is a key that can have the same value across multiple instances, and it is used to match instances based on their shared value. It is not important what the attribute's name is (even though we map based on this attribute), but rather the value itself when performing the matching between instances. For example, in an onboarding process for a user, you hold a unique personal identification number (SSN), and someone else needs a portion of your process, specifically the value of your input (SSN). The communication works as follows: you receive a message on a Kafka topic - `${kafka.topic.naming.prefix}.core.message.event.process${kafka.topic.naming.suffix}`. The engine listens here and writes the response. ## Message events configuration * `attachedTo`: a property that applies to boundary events * `messageName`: a unique name at the database level, should be the same for throw and catch events * `correlationKey`: a process variable used to uniquely identify the instance to which the message is sent * `data`: allows defining the JSON message body mapping as output and input ### Data example ```json { "document":{ "documentId": "${document.id}", "documentUrl": "${document.url}" } } ``` # Intermediate message events in business processes Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-intermediate/example-intermediate-message-events Business processes often involve dynamic communication and coordination between different stages or departments. Intermediate Message Events play an important role in orchestrating information exchange, ensuring effective synchronization, and enhancing the overall efficiency of these processes. * [Throw and catch on sequence - credit card request process example](#throw-and-catch-on-sequence---credit-card-request-process-example) * [Throw and catch - interprocess communication](#interprocess-communication-with-throw-and-catch-events) ## Throw and catch on sequence - Credit card request process example ### Business scenario In the following example, we'll explore a credit card request process that encompasses the initiation of a customer's request, verification based on income rules, approval or rejection pathways, and communication between the client and back office. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_catch_intermediate_process.png) #### Activities ##### Default swimlane (client) * **Start Event:** Marks the commencement of the process. * **User Task 1:** Customer Requests New Credit Card - Involves the customer submitting a request for a new credit card. * **Exclusive Gateway:** The process diverges based on the verification result (dependent on income rules). * **Path A (Positive Verification):** * **User Task 2:** Approve Credit Card Application - The bank approves the credit card application. * **End Event:** Denotes the conclusion of the process for approved applications. * **Path B (Negative Verification):** * **Parallel Gateway Open:** Creates two parallel zones. * **First Parallel Zone:** * **User Task 3:** Reject Credit Card Application - The bank rejects the credit card application. * **Message Throw Intermediate Event:** Signals the rejection, throwing a message to notify the back office department. * **End Event:** Signifies the end of the process for rejected applications. * **Second Parallel Zone:** * **User Task 3:** Reject Credit Card Application - The bank rejects the credit card application. * **Message Catch Intermediate Event:** The back office department is notified about the rejection. * **Send Message Task**: A notification is sent via email to the user about the rejection. * **End Event:** Signifies the end of the process for rejected applications. ##### Backoffice swimlane * **Message Catch Intermediate Event:** The back office department awaits a message to proceed with credit card issuance. * **Send Message Task:** Send Rejection Letter - Involves sending a rejection letter to the customer. ### Sequence flow ```mermaid graph TD subgraph Default Swimlane StartEvent[Start Process] UserTask1[User Task 1: Customer Requests New Credit Card] Gateway1{Exclusive Gateway} UserTask2[User Task 2: Approve Credit Card Application] endA[End Event: End approved scenario] ParallelGateway{Parallel Gateway} UserTask3A[User Task 3: Reject Credit Card Application] MessageThrow[Message Throw Intermediate Event: Throwing a message to notify the back office department.] Gateway2{Close Parallel} endC[End Event: Signifies the end of the process for rejected applications.] end subgraph Backoffice Swimlane MessageCatch SendEmailTask end StartEvent -->|Start Process| UserTask1 UserTask1 -->|Income Verification| Gateway1 Gateway1 -->|Positive Verification| UserTask2 UserTask2 -->|Approved| endA Gateway1 -->|Negative Verification| ParallelGateway ParallelGateway -->|First Parallel Zone| UserTask3A UserTask3A -->|Credit Card Rejected| MessageThrow MessageThrow --> Gateway2 -->|Second Parallel Zone| MessageCatch MessageCatch --> SendEmailTask SendEmailTask --> Gateway2 Gateway2 -->|End| endC ``` ### Message flows A message flow connects the Message Throw Intermediate Event to the Message Catch Intermediate Event, symbolizing the communication of credit card approval from the credit card approval task to the back office department. In summary, when a customer initiates a new credit card request, the bank verifies the information. If declined, a message is thrown to notify the back office department. The Message Catch Intermediate Event in the back office awaits this message to proceed with issuing and sending the rejection letter to the customer. ### Configuring the BPMN process To implement the illustrated BPMN process for the credit card request, follow these configuration steps: **FLOWX.AI Designer**: Open FLOWX.AI Designer. **Draw BPMN Diagram**: Import the provided BPMN diagram into FLOWX.AI Designer or recreate it by drawing the necessary elements. **Customize Swimlanes**: Set up the "Default" and "Backoffice" swimlanes to represent different departments or stakeholders involved in the process. This helps visually organize and assign tasks to specific areas. **Define User Tasks**: Specify the details for each user task. Configure User Task 1, User Task 2, and User Task 3 with appropriate screens. * **User Task 1** - *customer\_request\_new\_credit\_card* We will use the value from `application.income` key added on the slider UI element to create an MVEL business rule in the next step. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task1_interm.gif) * **User Task 2** - *approve\_credit\_card\_request* ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task2_interm.gif) In this screen, we configured a modal to display the approval. * **User Task 3** - *reject\_credit\_card\_request* ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task3_interm.gif) **Configure Gateways**: Adjust the conditions for the Exclusive Gateway based on your business rules. Define the conditions for positive and negative verifications, guiding the process down the appropriate paths. In our example, we used an MVEL rule to determine eligibility based on the income of the user. We used the `application.income` key configured in the first user task to create the rule. ![MVEL Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example_gateway.png) Also, add Parallel gateways to open/close parallel paths. ![Parallel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/parallel_open_close.gif) **Set Message Events**: Configure the Message Throw and Message Catch Intermediate Events in the "Default" and "Backoffice" swimlanes, respectively. Ensure that the Message Catch Intermediate Event in the "Backoffice" swimlane is set up to wait for the specific message thrown by the Message Throw event. This facilitates communication between different stages of the process. **Define End Events**: Customize the End Events for approved and rejected applications in the "Default" swimlane. Also, set an end event in the "Backoffice" swimlane to indicate the completion of the back-office tasks. **Configure Send Message Task**: Set up the Send Message Task in the "Backoffice" swimlane to send a rejection letter as a notification to the user. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/sending_a_notification.png) Define the content of the rejection letter, the method of notification, and any additional details required for a seamless user experience. More details on how to configure a notification can be found in the following section: [**Sending a notification**](../../../../platform-deep-dive/plugins/custom-plugins/notifications-plugin/sending-a-notification) **Validate and Test**: Validate the BPMN diagram for correctness and completeness. Test the process flow by simulating different scenarios, such as positive and negative verifications. ### Configuring intermediate message events Configuring message events is a crucial step in orchestrating effective communication and synchronization within a business process. Whether you are initiating a message throw or awaiting a specific message with a catch, the configuration process ensures information exchange between different components of the process. In this section, we explore the essential steps and parameters involved in setting up message events to optimize your BPMN processes. ### Message throw intermediate event A Message Throw Intermediate Event is an event in a process where a message is sent to trigger communication or action with another part of the process (can be correlated with a catch event). It represents the act of throwing a message to initiate a specific task or notification. The event creates a connection between the sending and receiving components, allowing information or instructions to be transmitted. Once the message is thrown, the process continues its flow while expecting a response or further actions from the receiving component. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_intrmdt.png) #### General Configuration * **Can go back?** - Setting this to true allows users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable. * **Correlate with catch message events** - The dropdown contains all catch messages from the process definitions accessible to the user, in our example: `throwcatchsequenceloan` It is imperative to define the message for the catch event first. This ensures its availability in the dropdown menu when configuring the throw intermediate event. * **Correlation key** - This is a process key that uniquely identifies the instance to which the message is sent. In our example, we utilized the `processInstanceId` as the identifier, dynamically generated at runtime. This key is crucial for establishing a clear and distinct connection between the sender and recipient in the messaging process. A correlation key is a key that can have the same value across multiple instances, and it is used to match instances based on their shared value. It is not important what the attribute's name is (even though we map based on this attribute), but rather the value itself when performing the matching between instances. * **The Send data field** - This feature empowers you to define a JSON structure containing the data to be transmitted alongside the message. In our illustrative example, we utilized dynamic data originating from user input, specifically bound to a slider UI element. ```json {"value": "${application.income}"} ``` * **Stage** - Assign a stage to the node. In the end, this is what we have: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_config.png) ### Message catch intermediate event A Message Catch Intermediate Event is a type of event in a process that waits for a specific message before continuing with the process flow. It enables the process to synchronize and control the flow based on the arrival of specific messages, ensuring proper coordination between process instances. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png) #### General Configuration * **Can go back?** - Setting this to true allows users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable. * **Correlate with throwing events** - The dropdown contains all catch messages from the process definitions accessible to the user (must be the same as the one assigned in Message throw intermediate event) * **Correlation key** - Process key used to establish a correlation between the received message and a specific process instance (must be the same as the one assigned in Message throw intermediate event). * **Receive data** - The process key that will be used to store the data received from the throw event along with the message. * **Stage** - Assign a stage to the node. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png) ### Testing the final result After configuring the BPMN process and setting up all the nodes, it is crucial to thoroughly test the process to ensure its accuracy and effectiveness. We will test the path where the user gets rejected. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/testing_the_proc_interm.gif) In the end, the user will receive this notification via email: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/notification_received.png) ## Interprocess communication with throw and catch events Facilitate communication between different processes by using message intermediate events. ### Business scenario Consider a Bank Loan Approval process where the parent process initiates a loan application. During the execution, it throws a message to a subprocess responsible for additional verification. #### Activities **Parent Process:** * **Start Event:** A customer initiates a loan application. * **Start Subprocess:** Initiates a subprocess for additional verification. * **User Task:** Basic verification steps are performed in the parent process. * **Throw Message:** After the basic verification, a message is thrown to indicate that the loan application is ready for detailed verification. * **End Event:** The parent process concludes. **Subprocess:** * **Start Event:** The subprocess is triggered by the message thrown from the parent process. * **Catch Message:** The subprocess catches the message, indicating that the loan application is ready for detailed verification. * *(Perform Detailed Verification and Analysis)* * **End Event:** The subprocess concludes. ### Sequence flow ```mermaid graph TD subgraph Parent Process a[Start] b[Start Subprocess] c[Throw message to another process] d[User Task] e[End] end subgraph Subprocess f[Start] g[Catch event in subprocess] h[End] end a --> b --> c --> d --> e f --> g --> h c --> g ``` ### Message flows * The parent subprocess triggers the subprocess run node, initiating the child process. * Within the child process, a message catch event waits for and processes the message thrown by the parent subprocess. ### Configuring the parent process (throw event) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_and_catch_subpr.png) **Open **FlowX.AI Designer** and create a new process**. **Add a User Task for user input**. * Within the designer interface, add a "User Task" element to collect user input. Configure the user task to capture the necessary information that will be sent along with the message. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task_loan_subrp.gif) **Integrate a [**Call activity**](../../../node/call-subprocess-tasks/call-activity-node.mdx) node**. * Add a "Subprocess Run Node" and configure it: * **Start Async** - Enable this option. When subprocesses are initiated in sync mode, they notify the parent process upon completion. The parent process then manages the reception of process data from the child and resumes its flow accordingly ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_run_node_cfg.png) * Add and configure the "Start Subprocess" action: * **Parameters**: * **Subprocess name** - Specify the name of the process containing the catch message event. * **Branch** - Choose the desired branch from the dropdown menu. * **Version** - Indicate the type of version to be utilized within the subprocess. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_subprocess_configuration.png) For a more comprehensive guide on configuring the "Start Subprocess" action, refer to the following section: [Start Subprocess action](../../../../building-blocks/actions/start-subprocess-action) **Insert a Throw Event for Message Initiation**. * Add a "Throw Event" to the canvas, indicating the initiation of a message. * Configure the throw message intermediate event node: * **Correlate with catch message events** - The dropdown contains all catch messages from the process definitions accessible to the user, in our example: `throwcatchDocs` * **Correlation key** - This is a process key that uniquely identifies the instance to which the message is sent. In our example, we utilized the `processInstanceId` as the identifier, dynamically generated at runtime. This key is crucial for establishing a clear and distinct connection between the sender and recipient in the messaging process. * **The Send data field** - This feature empowers you to define a JSON structure containing the data to be transmitted alongside the message. In our illustrative example, we utilized dynamic data originating from user input, specifically bound to some slider UI elements. ```json { "client_details": { "clientIncome": ${application.income}, "loanAmount": ${application.loan.amount}, "loanTerm": ${application.loan.term} } } ``` ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_in_anthr_proc.png) ### Configuring the subprocess (catch event) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_from_anthr_proc.png) Configure the node: * **Correlate with throwing events** - Utilize the same correlation settings added for the associated throw message event. * **Correlation Key** - Set the correlation key to the parent process instance ID, identified as `parentProcessInstanceId`. * **Receive data** - Specify the process key that will store the data received from the throw event along with the corresponding message. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_interm_from_anthr_prc.png) * Integrate and Fine-Tune a Service Task for Additional Verification. * Incorporate a service task to execute the additional verification process. Tailor the configuration to align with your preferred method of conducting supplementary checks. ### Throw with multiple catch events Download the example # Message catch intermediate event Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-intermediate/message-catch-intermediate-event A Message Catch Intermediate Event is a type of event in a process that waits for a specific message before continuing with the process flow. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_intermediate_event.png#center) **Why it is important?** It enables the process to synchronize and control the flow based on the arrival of specific messages, ensuring proper coordination between process instances. Similar to the message catch boundary event, the message catch intermediate event is important because it facilitates the communication and coordination between process instances through messages. By incorporating this event, the process can effectively synchronize and control the flow based on the arrival of specific messages. Message Catch Intermediate Event can be used as a standalone node, this means that it will block a process until it receives an event. ## Configuring a message catch intermediate event Imagine a process where multiple tasks are executed in sequence, but the execution of a particular task depends on the arrival of a certain message. By incorporating a message catch intermediate event after the preceding task, the process will pause until the expected message is received. This ensures that the subsequent task is not executed prematurely and allows for the synchronization of events within the process. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png) #### General config * **Can go back?** - setting this to true will allow users to return to this step after completing it, when encountering a step with `canGoBack` false, all steps found behind it will become unavailable * **Correlate with throwing message events** - the dropdown contains all catch messages from the process definitions accessible to the user * **Correlation key** - process key used to establish a correlation between the received message and a specific process instance * **Receive data** - the process key that will be used to store the data received along with the message * **Stage** - assign a stage to the node ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png) # Message intermediate events overview Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-intermediate/message-intermediate An intermediate event is an occurrence situated between a start and an end event in a process or system. It is represented by a circle with a double line. This event can either catch or throw information, and the directional flow is indicated by connecting objects, determining whether the event is catching or throwing information. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_message_events.png) ### Message throw intermediate event This event throws a message and continues with the process flow. It enables the sending of a message to a unique destination. ### Message catch intermediate event This event waits for a message to be caught before continuing with the process flow. # Message throw intermediate event Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-events/message-intermediate/message-throw-intermediate-event Using a Throw intermediate event is like throwing a message to tell someone about something. After throwing the message, the process keeps going, and other parts of the process can listen to that message. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/throw_message_event.png#center) **Why it is important?** The Message Throw Intermediate Event is important because it allows different parts of a process to communicate and share information with each other. ## Configuring a message throw intermediate event A Message throw intermediate event is an event in a process where a message is sent to trigger a communication or action with another part of the process (can be correlated with a catch event). It represents the act of throwing a message to initiate a specific task or notification. The event creates a connection between the sending and receiving components, allowing information or instructions to be transmitted. Once the message is thrown, the process continues its flow while expecting a response or further actions from the receiving component. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_intrmdt.png) #### General config * **Can go back?** - setting this to true will allow users to return to this step after completing it, when encountering a step with `canGoBack` false, all steps found behind it will become unavailable * **Correlate with catch events** - the dropdown contains all catch messages from the process definitions accessible to the user * **Correlation key** - is a process key that uniquely identifies the instance to which the message is sent * **The data field** - allows the user to define a JSON structure with the data to be sent along with the message * **Stage** - assign a stage to the node ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_config.png) # Send message/receive message tasks Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/message-send-received-task-node Send message task and Receive message task nodes are used to handle the interaction between a running process and external systems. This is done using Kafka. ## Send message task This node is used to configure messages that should be sent to external systems. ![Send Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send-task_node.svg#center) ### Configuring a send message task Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a send message task: #### General configuration Inside the **General Config** tab, you have the following properties: * **Node Name** - the name of the node * **Can Go Back** - switching this option to true will allow users to return to this step after completing it When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable. * [**Swimlane**](../../platform-deep-dive/user-roles-management/swimlanes) - choose a swimlane (if there are multiple swimlanes on the process) to ensure only certain user roles have access to certain process nodes; if there are no multiple swimlanes, the value is **Default** * [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages) - assign a stage to the node ![General Config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_task_action.png) To configure a send message task, we first need to add a new node and then configure an **action** (**Kafka Send Action** type): 1. Open **Process Designer** and start configuring a process. 2. Add a **send message task** node. 3. Select the **send message task** node and open the **Node Configuration**. 4. Add an **action** , the type of the action set to **Kafka Send Action**. 5. A few action parameters will need to be filled in depending on the selected action type. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_send_task.gif) Multiple options are available for this type of action and can be configured via the FLOWX.AI Designer. To configure and [add an action to a node](../../flowx-designer/managing-a-process-flow/adding-an-action-to-a-node), use the **Actions** tab at the node level, 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](../actions/actions) on nodes in the process. We recommend defining an action naming standard to easily find the process actions * **Order** - if multiple actions are defined on the same node, set the running order 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](./timer-events/timer-expressions#iso-8601) (for example, a delay of 30 seconds will be set up as `PT30S`) * **Action Type** - should be set to **Kafka Send Action** for actions used to send messages to external systems * **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 the process is a functionality that allows you to go back in a business process and redo a series of previous actions in the process, or for more details, check [**Moving a Token Backwards in a Process**](../../flowx-designer/managing-a-process-flow/moving-a-token-backwards-in-a-process) section ![Action Edit](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_action_edit.png) #### 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](./user-task-node) section) You can configure **Data to Send** option only when the action **trigger type** is **Manual**. ![Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/parameters_message_send.gif) For more information about Kafka, check the following sections: ### Example of a send message task usage Send a message to a CRM integration to request a search in the local database: #### Action Edit * **Name** - pick a name that makes it easy to figure out what this action does, for example, `sendRequestToSearchClient` * **Order** - 1 * **Timer Expression** - this remains empty if we want the action to be triggered as soon as the token reaches this node * **Action Type** - Kafka Send Action * **Trigger Type** - *Automatic* - to trigger this action automatically * **Required Type** - *Mandatory* - to make sure this action will be run before advancing to the next node * **Repeatable** - false, it only needs to run once #### Parameters Parameters can be added either using the **Custom** option (where you configure everything on the spot) or by using **From Integration** and import parameters already defined in an integration. More details about **Integrations Management** you can find [here](../../platform-deep-dive/core-extensions/integration-management/integration-management-overview). ##### Custom * **Topics** - `ai.flowx.in.crm.search.v1` the Kafka topic on which the CRM listens for requests * **Message** - `{ "clientType": "${application.client.clientType}", "personalNumber": "${personalNumber.client.personalNumber}" }` - the message payload will have two keys, `clientType` and `personalNumber`, both with values from the process instance * **Headers** - `{"processInstanceId": ${processInstanceId}}` ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_param1.png) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_param2.png) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_param3.png) ## Receive Message Task This type of node is used when we need to wait for a reply from an external system. ![Receive Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/receive-task%20_node.svg#center) The reply from the external system will be saved in the process instance values, on a specified key. If the message needs to be processed at a later time, a timeout can be set using the [ISO 8601](./timer-events/timer-expressions) format. For example, let's think about a CRM microservice that waits to receive requests to look for a user in a database. It will send back the response when a topic is configured to listen for the response. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_receive_message.png) ### Configuring a Receive Message Task The values you need to configure for this node are the following: * **Topic Name** - the topic name where the [process engine](../../platform-deep-dive/core-components/flowx-engine) listens for the response (this should be added to the platform and match the topic naming rule for the engine to listen to it) - `ai.flowx.out.crm.search.v1` A naming pattern must be defined on the process engine to use the defined topics. It is important to know that all the events that start with a configured pattern will be consumed by the Engine. For example, `KAFKA_TOPIC_PATTERN` is the topic name pattern that the Engine listens to for incoming Kafka events. * **Key Name** - will hold the result received from the external system; if the key already exists in the process values, it will be overwritten - `crmResponse` For more information about Kafka configuration, click [here](../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka). ![Example of a Receive Message Task for a CRM integration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_receive_kafka_ex.png) #### From integration After defining one integration (inside [Integration Management](../../platform-deep-dive/core-extensions/integration-management/)), you can open a compatible node and start using already defined integrations. * **Topics** - topics defined in your integration * **Message** - the **Message Data Model** from your integration * **Headers** - all integrations have `processInstanceId` as a default header parameter; add any other relevant parameters ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_send_from_integr.gif) # BPMN nodes Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/node A Business Process Model and Notation (BPMN) node is a visual representation of a point in your process. Nodes are added at specific process points to denote the entrance or transition of a record within the process. For a comprehensive understanding of BPMN, start with the following section: [**Intro to BPMN**](/4.0/docs/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn). ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/BPMN%20nodes.png) FlowX.AI platforms support various node types, each requiring distinct configurations to fulfill its role in the business flow. ## Types of BPMN nodes Let's explore the key types of BPMN nodes available in FlowX: * **Start and End nodes** - Mark the initiation and conclusion of a [process flow](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn). A [process definition](../process/process-definition) may have multiple start nodes (each linked with a start condition) and end nodes based on the flow outcomes. * **Send Message and Receive Message tasks** - Used for communication with external systems, integrations, and plugins. * **Message Events** - Capture interactions between different process participants by referencing messages. * **Timer Events** - Introduce time-based behavior into processes, triggering actions at specific intervals, durations, or cycles. They support configurations like specific dates, durations, or recurring cycles and can pause, start, or monitor tasks based on time conditions. * **Error Events** - Manage error handling in processes by interrupting tasks or subprocesses upon specific error conditions. Configured as boundary events, they catch and handle errors thrown within the process, ensuring robust error management and control. * **Task** nodes - Added when a [business rule](../actions/business-rule-action/business-rule-action) needs to execute during a process flow. * **User Task** nodes - Configure the appearance and behavior of the UI and send data to custom components. * **Exclusive Gateways** - Mark decision points in the process flow, determining the branch to be followed. * **Parallel Gateways** - Split the process flow into two or more [branches](../../flowx-designer/managing-a-process-flow/adding-more-flow-branches) occurring simultaneously. * **Call Subprocess Tasks**: * **Call Activity** - Call activity is a node that provides advanced options for starting **subprocesses**. * **Start Embedded Subprocess** - The Start Embedded Subprocess node initiates subprocesses within a parent process, allowing for encapsulated functionality and enhanced process management. * **Boundary Events** - Specialized nodes that attach to specific tasks or subprocesses to handle predefined events during execution. They can be configured as interrupting or non-interrupting, with the following key types: * **Message Catch Boundary Event** - Waits for a specific message while the task or subprocess is active, interrupting or initiating a parallel flow based on configuration. * **Timer Boundary Event** - Triggers based on a specific time duration, date, or cycle. It can interrupt a task or start an additional flow without stopping the task. * **Error Boundary Event** - Interrupts the associated task or subprocess upon an error, redirecting the process to a defined error-handling flow. Boundary events enhance process flexibility by enabling workflows to adapt dynamically to real-time conditions, ensuring robust error, message, and timeout handling. For comprehensive insights into BPMN and its various node types, explore our course at FlowX Academy: * What's BPMN (Business Process Model Notation) and how does it work? * How is BPMN used in FlowX? ### Boundary events Boundary events attach to the boundary of specific nodes (e.g., User Task, Service Task, Subprocess, or Call Activity) and are triggered when predefined conditions occur. These events can interrupt the ongoing activity or allow it to continue while starting a parallel flow. They include: * **Message Catch Boundary Event**: Waits for and responds to a specific incoming message during a task. * **Timer Boundary Event**: Activates based on elapsed time, a specific date, or a recurring cycle, useful for timeouts or deadlines. * **Error Boundary Event**: Catches errors during a task or subprocess and redirects the process flow to handle them appropriately. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2012.17.17.png) **Compatibility Matrix**: Boundary events can attach to the following node types: * **User Task** * **Service Task** * **Send Message/Receive Message Tasks** * **Subprocess (Embedded and Call Activity)** Boundary events are a critical element for creating resilient and adaptive processes, enabling efficient error handling, timeout management, and real-time interactions. After gaining a comprehensive overview of each node, you can experiment with them to create a process. More details are available in the following section: [Managing a process flow](../../flowx-designer/managing-a-process-flow/) # Parallel gateway Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/parallel-gateway When you have multiple operations that can be executed concurrently, the Parallel Gateway becomes a valuable tool. This type of node creates a parallel section within the process, particularly useful for tasks that can run independently without waiting for each other. It's essential to close each parallel section with another Parallel Gateway node. ## Configuring parallel paths ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_parallel.png#center) This node requires no special configuration and can initiate two or more parallel paths. It's important to note that the closing Parallel node, which is required to conclude the parallel section, will wait for all branches to complete before advancing to the next node. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/parallel_gateways.png) ### Configuration example Let's consider a scenario involving a Paid Time Off (PTO) request. We have two distinct flows: one for the HR department and another for the manager. Initially, two tokens are generated—one for each parallel path. A third token is created when both parallel paths converge at the closing parallel gateway. In the HR flow, in our example, the request is automatically approved. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/hr_flow.gif) Now, we await the second flow, which requires user input. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/manager_flow.gif) After the tokens from the parallel paths have completed their execution, a third token initiates from the closing parallel gateway. # Start/end nodes Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/start-end-node Let's go through all the options for configuring start and end nodes for a process definition. ## Start node The start node represents the beginning of a process and it is mandatory to add one when creating a process. ![Start node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/start_node.png#center) A process can have one or more start nodes. If you defined multiple start nodes, each should have a start condition value configured. When starting a new process instance the desired start condition should be used. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/start_node_example.png) ### Configuring a start node Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a **start node**: * [General Config](#general-config) * [Start condition](#start-condition) #### General Config * **Node name** - the name of the node * **Can go back** - switching this option to true will allow users to return to this step after completing it When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable. * [**Swimlane**](../../platform-deep-dive/user-roles-management/swimlanes) - choose a swimlane (if there are multiple swimlanes on the process) to make sure only certain user roles have access to certain process nodes- if there are no multiple swimlanes, the value is **Default** * [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages)- assign a stage to the node #### Start condition The start condition should be set as a string value. This string value will need to be set on the payload for the start process request on the `startCondition` key. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/start_node_condition.png) To test the start condition, we can send a start request via REST: ``` POST {{processUrl}}/api/process/{{processName}}/start { "startCondition": "PF" } ``` #### Error handling on start condition If a request is made to start a process with a start condition that does not match any start node, an error will be generated. Let's take the previous example and assume we send an incorrect value for the start condition: ``` POST {{processUrl}}/api/process/{{processName}}/start { "startCondition": "PJ" } ``` A response with the error code `bad request` and title `Start node for process definition not found`will be sent in this case: ```json { "entityName": "ai.flowx.process.definition.domain.NodeDefinition", "defaultMessage": "Start node for process definition not found.", "errorKey": "error.validation.process_instance.start_node_for_process_def_missing", "type": "https://www.jhipster.tech/problem/problem-with-message", "title": "Start node for process definition not found.", "status": 400, "message": "error.validation.process_instance.start_node_for_process_def_missing", "params": "ai.flowx.process.definition.domain.NodeDefinition" } ``` ## End node ![End Event](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/end-event.png#center) An end node is used to mark where the process finishes. When the process reaches this node, the process is considered completed and its status will be set to `Finished`. ### Configuring an end node Multiple end nodes can be used to show different end states. The configuration is similar to the start node. ![End node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/end_node.png) # Task node Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/task-node A task node refers to a task that utilizes various services, such as Web services, automated applications, or other similar services, to accomplish a particular task. ![Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/service_task.png#center) This type of node finds application in multiple scenarios, including: * Executing a [**business rule**](../actions/business-rule-action/) on the process instance data * Initiating a [**subprocess**](../actions/start-subprocess-action) * Transferring data from a subprocess to the parent process * Transmitting data to frontend applications ## Configuring task nodes One or more actions can be configured on a task node. The actions are executed in the configured order. Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a task node: #### General Config * **Node name** - the name of the node * **Can go back** - switching this option to true will allow users to return to this step after completing it ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/task_node_general_config.png) When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable. * [**Swimlane**](../../platform-deep-dive/user-roles-management/swimlanes) - choose a swimlane (if there are multiple swimlanes on the process) to make sure only certain user roles have access to certain process nodes- if there are no multiple swimlanes, the value is **Default** * [**Stage** ](../../platform-deep-dive/core-extensions/task-management/using-stages)- assign a stage to the node #### Response Timeout * **Response timeout** - can be triggered if, for example, a topic that you define and add in the [Data stream topics](#data-stream-topics) tab does not respect the pattern, the format used for this is [ISO 8601 duration format](https://www.w3.org/TR/NOTE-datetime)(for example, a delay of 30s will be set up like `PT30S`) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/task_node_response_timeout.png) #### Data stream topics * **Topic Name** - the topic name where the [process engine](../../platform-deep-dive/core-components/flowx-engine) listens for the response (this should be added to the platform and match the topic naming rule for the engine to listen to it) - available for UPDATES topics (Kafka receive events) A naming pattern must be defined on the [process engine configuration](../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) to use the defined topics. It is important to know that all the events that start with a configured pattern will be consumed by the Engine. For example, `KAFKA_TOPIC_PATTERN` is the topic name pattern where the Engine listens for incoming Kafka events. * **Key Name** - will hold the result received from the external system, if the key already exists in the process values, it will be overwritten #### Task Management * **Update task management** - force [Task Management Plugin](../../platform-deep-dive/core-extensions/task-management/task-management-overview) to update information about this process after this node ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/task_node_task_management.png) ## Configuring task nodes actions Multiple options are available when configuring an action on a task node. To configure and add an action to a node, use the **Actions** tab at the node level, which has the following configuration options: * [Action Edit](#action-edit) * [Parameters](#parameters) #### Action Edit Depending on the type of the [**action**](../actions/actions), different properties are available, let's take a [**business rule**](../actions/business-rule-action/business-rule-action) as an example. 1. **Name** - used internally to differentiate between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions. 2. **Order** - if multiple actions are defined on the same node, their running order should be set using this option 3. **Timer Expression** - 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 30s will be set up like `PT30S`) 4. **Action type** - defines the appropriate action type 5. **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. 6. **Required type** - (options are Mandatory/Optional) - automatic actions can only be defined as mandatory. Manual actions can be defined as mandatory or optional. 7. **Repeatable** - should be checked if the action can be triggered multiple times ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/task_node_action_edit.png) #### Parameters Depending on the type of the [**action**](../actions/actions), different properties are available. We refer to a **Business rule** as an example 1. **Business Rules** - business rules can be attached to a node by using actions with action rules on them, these can be specified using [DMN rules](../actions/business-rule-action/dmn-business-rule-action), [MVEL](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-mvel) expressions, or scripts written in Javascript, Python, or Groovy. ### Business Rule action A [business rule](../actions/business-rule-action/business-rule-action) is a Task action that allows a script to run. For now, the following script languages are supported: * [**MVEL**](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-mvel) * **JavaScript (Nashorn)** * **Python (Jython)** * **Groovy** * [**DMN**](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-dmn) - more details about a DMN business rule configuration can be found [here](../actions/business-rule-action/dmn-business-rule-action) For more details on how to configure a Business Rule action, check the following section: Being an event-driven platform FLOWX uses web socket communication in order to push events from the frontend application. For more details on how to configure a Send data to user interface action, check the following section: Upload file action will be used to upload a file from the frontend application and send it via a Kafka topic to the document management system. For more details on how to configure an Upload File action, check the following section: In order to create reusability between business processes, as well as split complex processes into smaller, easier-to-maintain flows, the start subprocess business rule can be used to trigger the same sequence multiple times. For more details on how to configure a Business Rule action, check the following section: Used for copying data in the subprocess from its parent process. For more details about the configuration, check the following section: # Timer boundary event Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/timer-events/timer-boundary-event A Timer Boundary Event in Business Process Model and Notation (BPMN) is a specialized event attached to a specific task or subprocess within a process. It activates when a predefined time condition—such as a duration, deadline, or specific date—is met while the associated task or subprocess is still in progress. This event is used to integrate time-related triggers into workflows, allowing processes to respond automatically to time-sensitive requirements. It is particularly useful for enforcing deadlines, scheduling periodic actions, or sending notifications, ensuring that time-critical steps are seamlessly incorporated into the overall process design.ary Events are utilized to incorporate time-related conditions into processes, enabling actions to be taken at specified time intervals, deadlines, or specific dates. This capability is especially valuable for scenarios where time-sensitive actions or notifications need to be integrated seamlessly within process flows. ### Compatibility matrix for Timer Events **Timer Events** can be applied to various contexts within BPMN processes. The table below outlines their compatibility with different node types: | **Node Type** | **Timer Event - Interrupting** | **Timer Event - Non-Interrupting** | | ----------------------------- | ------------------------------ | ---------------------------------- | | **User Task** | Yes | Yes | | **Service Task** | Yes | Yes | | **Send Message Task** | Yes | Yes | | **Receive Message Task** | Yes | Yes | | **Start Embedded Subprocess** | No | No | | **Call Activity** | Yes | Yes | ## Timer boundary event - interrupting A Timer Boundary Event is an event attached to a specific activity (task or subprocess) that is triggered when a specified time duration or date is reached. It can interrupt the ongoing activity and initiate a transition. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_interrupting.svg#center) ### Configuration For Timer Boundary Events - Interrupting, the following values can be configured: | Field | Validations | Accepted Values | | ---------- | ----------- | -------------------------------- | | Definition | Mandatory | ISO 8601 formats (date/duration) | | | | Process param | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_timer_event.png) ### General rules * When the token enters the parent activity, a scheduler is set, and it waits for the timer event to be triggered. * When the timer is triggered, the ongoing activity is terminated, and the process continues with the defined transition. ## Timer boundary event - non-interrupting A Timer Boundary Event is an event attached to a specific activity (task or subprocess) that is triggered when a specified time duration or date is reached. It can trigger independently of the ongoing activity and initiate a parallel path. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_non_interrupting.svg#center) ### Configuration For Timer Boundary Events - Non-Interrupting, the following values can be configured: | Field | Validations | Accepted Values | | ---------- | ----------- | -------------------------------- | | Definition | Mandatory | ISO 8601 formats (date/duration) | | | | Process param | ### General rules * When a token arrives at a node with a Timer Boundary Event - Non-Interrupting associated: * A trigger is scheduled, but the current token execution remains unaffected. * When the token enters the parent activity, a scheduler is set, and it waits for the timer event to be triggered. * If the timer is a cycle, it is rescheduled for the specified number of repetitions. * The scheduler is canceled if the token leaves the activity before it is triggered. # Timer events Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/timer-events/timer-events Timer event nodes are a powerful feature in BPMN that allow you to introduce time-based behavior into your processes. These nodes enable you to trigger specific actions or events at predefined time intervals, durations, or cycles. With timer event nodes, you can design processes that respond to time-related conditions, ensuring smoother workflow execution and enhanced automation. There are three primary types of timer event nodes: * **Timer Start Event (interrupting/non-interrupting)**: This node initiates a process instance at a scheduled time, either interrupting or non-interrupting ongoing processes. It allows you to set a specific date, duration, or cycle for the process to start. You can configure it to trigger a process instance just once or repeatedly. * **Timer Intermediate Event** (interrupting): This node introduces time-based triggers within a process. It's used to pause the process execution until a specified time duration or date is reached. Once triggered, the process continues its execution. * **Timer Boundary Event (interrupting/non-interrupting)**: Attached to a task or subprocess, this node monitors the passage of time while the task is being executed. When the predefined time condition is met, the boundary event triggers an associated action, interrupting or non-interrupting the ongoing task or subprocess. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2014.37.56.png) ## Timers Timers introduce the ability to trigger events at specific time intervals. They can be configured in three different ways: as a date, a duration, or a cycle. These configurations can use static values or dynamic/computed values. * **Date**: Events triggered on a specific date and time. * Format: ISO 8601 (e.g., `2019-10-01T12:00:00Z` or `2019-10-02T08:09:40+02:00`) * **Time Duration**: Events triggered after a specified duration. * Format: ISO 8601 duration expression (`P(n)Y(n)M(n)DT(n)H(n)M(n)S`) * P: Duration designator * Y: Years * M: Months * D: Days * T: Time designator * H: Hours * M: Minutes * S: Seconds Examples: * `PT15S` - 15 seconds * `PT1H30M` - 1 hour and 30 minutes * `P14D` - 14 days * `P3Y6M4DT12H30M5S` - 3 years, 6 months, 4 days, 12 hours, 30 minutes, and 5 seconds ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_events_duration_date.gif) * **Time Cycle** (available for Timer Start Event): Events triggered at repeating intervals. * Option 1: ISO 8601 repeating intervals format (`R`) * Examples: * `R5/2023-08-29T15:30:00Z/PT2H`: Every 2 hours seconds, up to five times, starting with 29 August, 15:30 UTC time * `R/P1D`: Every day, infinitely ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_start_cycle.gif) * Option 2: Using cron expressions * Example: `0 0 9-17 * * MON-FRI`: Every hour on the hour from 9 a.m. to 5 p.m. UTC, Monday to Friday Important: Only Spring cron expressions are permissible for configuration. Refer to the [**official documentation**](https://docs.spring.io/spring-framework/4.0/docs/current/javadoc-api/org/springframework/scheduling/support/CronExpression.html) for detailed information on configuring Spring Cron expressions. Scheduled timer events are clearly indicated within the process definition list of an application at Runtime, as illustrated in the following example: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png) More information about timer expressions you can find in the below section: [Timer expressions](./timer-expressions) ## Configuration For each node type, the following timer types can be configured: | Node Type | Date | Duration | Cycle | | ------------------------ | ---- | -------- | ----- | | Timer Start Event | Yes | No | Yes | | Timer Intermediate Event | Yes | Yes | No | | Timer Boundary Event | Yes | Yes | No | A process definition version should have a single Timer Start Event per swmilane. For comprehensive details on each timer event node in this section, please refer to the corresponding documentation: # Timer expressions Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/timer-events/timer-expressions When working with FlowX.AI components, there are multiple scenarios in which timer expressions are needed. There are two timer expressions formats supported: * [**Cron expressions**](#cron-expressions) - used to define the expiry date on processes * [**ISO 8601**](#iso-8601) - used to define the duration of a response timeout or for a timer expression ### Cron expressions A cron expression is a string made up of **six mandatory subexpressions (fields) that each specifies an aspect of the schedule** (for example, `* * * * * *`). These fields, separated by white space, can contain any of the allowed values with various combinations of the allowed characters for that field. A field may be an asterisk (`*`), which always stands for “first-last”. For the day-of-the-month or day-of-the-week fields, a question mark (`?`) may be used instead of an asterisk. Important: Only Spring cron expressions are permissible for configuration. Refer to the [**official documentation**](https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression) for detailed information on configuring Spring Cron expressions. Subexpressions: 1. Seconds 2. Minutes 3. Hours 4. Day-of-Month 5. Month 6. Day-of-Week 7. Year (optional field) An example of a complete cron-expression is the string `0 0 12 ? * FRI` - which means **every Friday at 12:00:00 PM**. More details: [Scheduling cron expressions](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-cron-expression) #### Cron Expressions are used in the following example: * [**Process definition**](../../../building-blocks/process/process-definition) - **Expiry time** - a user can set up a `expiryTime` function on a process, for example, a delay of 30s will be set up like: ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_process_settings.png) ### ISO 8601 ISO 8601 is an international standard covering the worldwide exchange and communication of date and time-related data. It can be used to standardize the following: dates, time of delay, time intervals, recurring time intervals, etc. More details: [ISO 8601 date format](https://www.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_date_format.htm) [ISO 8601 duration format](https://www.digi.com/resources/documentation/digidocs//90001488-13/reference/r_iso_8601_duration_format.htm) #### ISO 8601 format is used in the following examples: * **Node config** - **Response Timeout** - can be triggered if, for example, a topic that you define and add in the **Data stream topics** tab does not respect the pattern ISO 8601 dates and times: | Format accepted | Value ranges | | -------------------- | -------------------------------------------- | | Year (Y) | YYYY, four-digit, abbreviatted to two-digit | | Month (M) | MM, 01 to 12 | | Week (W) | WW, 01 to 53 | | Day (D) | D, day of the week, 1 to 7 | | Hour (h) | hh, 00 to 23, 24:00:00 as the end time | | Minute (m) | mm, 00 to 59 | | Second (s) | ss, 00 to 59 | | Decimal fraction (f) | Fractions of seconds, any degree of accuracy | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_response_timeout.png) * [**Actions**](../../actions/actions) - **Timer expression** - it can be used if a delay is required on that action ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_action_edit.png) # Timer Intermediate Event (interrupting) Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/timer-events/timer-intermediate-event A Timer Intermediate Event (interrupting) is an event that is triggered based on a specified time duration or date. It is placed within the flow of a process and serves as a point of interruption and continuation. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_intermediate_event.png#center) ## Configuring a timer intermediate event (interrupting) | Field | Validations | Accepted Values | | ---------- | ----------- | -------------------------------- | | Definition | Mandatory | ISO 8601 formats (date/duration) | | | | Process param | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/intermediate_timer_eventz.png) ### Timer type: #### Date * event triggered on a specific date-time * ISO 8601 format (example: `2019-10-01T12:00:00Z` - UTC time, `2019-10-02T08:09:40+02:00`- UTC plus two hours zone offset) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_timer_date.png) #### Duration Event triggered after x duration after the token reached the timer node (or parent node) (example: `PT6S`). * Definition: * ISO * Cron * Process param ## General Rules * A Timer Intermediate Event is triggered based on its duration or date definition. * When the token enters a Timer Intermediate Event, a scheduler is set, and it waits for the timer event to be triggered. * After the timer is triggered, the process instance continues. # Timer start event (interrupting) Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/timer-events/timer-start-event A Timer Start Event initiates a process instance based on a specified time or schedule. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_start_interrupting.png#center) Please note that a process definition version can accommodate only one **Timer Start Event**. If a process definition contains versions with Start Timer Event nodes, only for the published version will generate a scheduler. ## Configuration Depending on the node type, the following timer types can be configured: | Node Type | Date | Duration | Cycle | | ----------------- | ---- | -------- | ----- | | Timer Start Event | Yes | No | Yes | Starting a process via registered timers requires sending a process start message to Kafka, necessitating a service account and authentication. For detailed guidance, refer to: [**Service Accounts**](../../../../setup-guides/access-management/configuring-an-iam-solution#scheduler-service-account) ### Timer type values * Date * Cycle #### Date Specifies an exact date and time for triggering the event. You can use ISO 8601 date format for accurate date-time representation. #### Scenario: employee onboarding reminder In this scenario, the Timer Start Event is used to trigger an employee onboarding process at a specific date and time. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/employee_onboarding_reminder.png) * Start Event (Timer Start Event) - New Hire Start Date * Timer Definition: 2023-09-01T09:00:00Z (ISO 8601 format) → This means the process will initiate automatically at the specified date and time. * This event serves as the trigger for the entire process. * Transition → Employee Onboarding Notification ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_timer_date.png) * Employee Onboarding Notification * Notify new employee about onboarding requirements by sending an email notification with a template called "Important Onboarding Information" * Actions: The HR team or automated system sends out necessary email information/documents, and instructions to the new employee. * After the notification is sent, the process transitions to the Complete Onboarding node. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/onboarding_notification.png) * Complete Onboarding * Employee onboarding completed * At this point, the employee's onboarding process is considered complete. * Actions: The employee may have completed required tasks, paperwork, or orientation sessions. #### Cycle Specifies a repeating interval for triggering the event. The cycle can be defined using ISO 8601 repeating intervals or cron expressions. ### Configuration according to timer type For each timer type, the following values can be configured: | Field | Validations | Accepted Values | | ----------------- | ------------------ | ---------------------------------- | | Definition | Mandatory | - Process param | | | | - ISO 8601 formats (date/duration) | | | | - Cron expressions (cycle) | | Start Time | Only for Cycle | - ISO 8601 format (date-time) | | | | - Process param | | End Time | Only for Cycle | - ISO 8601 format (date-time) | | | | - Process param | | Active/ Suspended | Default: Suspended | - Active | | | | - Suspended | The Start Timer Event supports either ISO 8601 formats or spring cron expressions for defining timer values. ### General rules * A process definition version can have a single published version, which can be a committed or a WIP version. * Only the published version generates a scheduler when it contains Start Timer Event nodes. * When a new committed version is published or when a WIP published version is updated with new Start Timer Event settings: * The scheduler is updated based on the settings in the published version. * The scheduler state (active or suspended) remains the same as before. # User task node Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/node/user-task-node This node represents an interaction with the user. It is used to display a piece of UI (defined in the UI Designer or a custom Angular component. You can also define actions available for the users to interact with the process. ## Configuring a user task node ![User Task Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/user_task_node.png#center) User task nodes allow you to define and configure UI templates and possible [actions](../actions/actions) for a certain template config node (ex: [button components](../ui-designer/ui-component-types/buttons)). #### General Config * **Node name** - the name of the node * **Can go back** - setting this to true will allow users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable. * [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages)- assign a stage to the node ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/node_config_new.png) When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable. #### Data stream topics * **Topic Name** - the topic name where the process engine listens for the response (this should be added to the platform and match the topic naming rule for the engine to listen to it) - available for UPDATES topics (Kafka receive events) A naming pattern must be defined on the [process engine configuration](../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) to use the defined topics. It is important to know that all the events that start with a configured pattern will be consumed by the Engine. For example, `KAFKA_TOPIC_PATTERN` is the topic name pattern where the Engine listens for incoming Kafka events. * **Key Name** - will hold the result received from the external system, if the key already exists in the process values, it will be overwritten #### Task Management * **Update task management** - force [Task Management](../../platform-deep-dive/core-extensions/task-management/task-management-overview) plugin to update information about this process after this node ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/user_task_node_task_mngmnt.png) ## Configuring the UI The **FlowX Designer** includes an intuitive [UI Designer](../ui-designer/ui-designer) (drag-and-drop editor) for creating diverse UI templates. You can use various elements from basic [buttons](../ui-designer/ui-component-types/buttons), indicators, and [forms](../ui-designer/ui-component-types/form-elements/), but also predefined [collections](../ui-designer/ui-component-types/collection/collection) or [prototypes](../ui-designer/ui-component-types/collection/collection_prototype). ### Accessing the UI Designer To access the **UI Designer**, follow the next steps: 1. Open **FLOWX Designer** and from the **Processes** tab select **Definitions**. 2. Select a **process** from the process definitions list. 3. Click the **Edit** **process** button. 4. Select a **user task** **node** from the Pro dcess Designer then click the **brush** icon to open the **UI Designer**. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/access_ui_designer.gif) ### Predefined components UI can be defined using the available components provided by FLOWX, using the UI Designer available at node level. Predefined components can be split in 3 categories: These elements are used to group different types of components, each having a different purpose: * [**Card**](../ui-designer/ui-component-types/root-components/card) - used to group and configure the layout for multiple **form elements.** * [**Container**](../ui-designer/ui-component-types/root-components/container) - used to group and configure the layout for multiple **components** of any type. * [**Custom**](../ui-designer/ui-component-types/root-components/custom) - these are Angular components developed in the container application and passed to the SDK at runtime, identified here by the component name More details in the following section: The root component can hold a hierarchical component structure. Available children for **Card** and **Container** are: * **Container** - used to group and align its children * **Form** - used to group and align form field elements (**inputs**, **radios**, **checkboxes**, etc) * **Image** - allows you to configure an image in the document * **Text** - a simple text can be configured via this component, basic configuration is available * **Hint** - multiple types of hints can be configured via this component * **Link** - used to configure a hyperlink that opens in a new tab * **Button** - Multiple options are available for configuration, the most important part being the possibility to add actions * **File Upload** - A specific type of button that allows you to select a file More details in the following section: This type of elements are used to allow the user to input data, and can be added only in a **Form** Component. They have have multiple properties that can be managed. 1. [**Input**](../ui-designer/ui-component-types/form-elements/input-form-field) - FLOWX form element that allows you to generate an input form filed 2. [**Select**](../ui-designer/ui-component-types/form-elements/select-form-field) - to add a dropdown 3. [**Checkbox**](../ui-designer/ui-component-types/form-elements/checkbox-form-field) - the user can select zero or more input from a set of options 4. [**Radio**](../ui-designer/ui-component-types/form-elements/radio-form-field) - the user is required to select one and only one input from a set of options 5. [**Datepicker**](../ui-designer/ui-component-types/form-elements/datepicker-form-field) - to select a date from a calendar picker 6. [**Switch**](../ui-designer/ui-component-types/form-elements/switch-form-field) - allows the user to toggle an option on or off More details in the following section: ### Custom components These are components developed in the web application and referenced here by component identifier. This will dictate where the component is displayed in the component hierarchy and what actions are available for the component. To add a custom component in the template config tree, we need to know its unique identifier and the data it should receive from the process model. More details in the following section: ## Displaying a UI Element in FlowX Designer When a process instance is started the web application will receive all the UI elements that can be displayed in that process. 1. Starting a Process: * The process is initiated by sending a request to the SDK. * This tells the server to start the specific process definition, in this case, named "DemoProcess". ```json ... { "processDefinitionName" : "DemoProcess", "tokens" : [ { "id" : 1961367, "startNodeId" : null, "embedNodeId" : null, "mainSwimlaneId" : null, "currentProcessVersionId" : 861684, "currentContext" : "main", "initiatorType" : null, "initiatorId" : null, "currentNodeId" : 921777, "currentNodeName" : null, "state" : "ACTIVE", "statusCurrentNode" : "ARRIVED", "dateUpdated" : "2024-09-23T09:29:06.668355Z", "uuid" : "60ecb3a1-0073-4d98-86b8-263bdaa95a8b" } ], "state" : "STARTED" ... } ``` 2. Displaying UI Elements: * As the process progresses, it reaches different nodes, in our example, "User Tasks" (nodes that require human interaction). * When a User Task is reached, a server message is sent to the application, instructing it to display the UI element associated with that users task. This UI element is essentially the part of the interface that the user will interact with at this point in the process. * Inside the `templateConfig` you can find all the UI elements configured on the node. In the following example you can see the details of a `CARD` UI element. ```json ... "templateConfig" : [ { "id" : 781824, "flowxUuid" : "771f7a69-2858-4ef4-8f58-a052c0cfe724", "componentIdentifier" : "CARD", "type" : "FLOWX", "order" : 1, "canGoBack" : true, "displayOptions" : { "flowxProps" : { "title" : "Company representative", "hasAccordion" : false }, "style" : { "widthType" : "fixed", "layoutType" : "grid", "flexLayout" : { "fxLayout" : "row wrap", "fxLayoutAlign" : "start start", "fxLayoutGap" : 10 }, "gridLayout" : { "columns" : 3, "position" : "start start", "columnGap" : 8, "rowGap" : 8 }, "gridChild" : { "colSpan" : 1, "rowSpan" : 1, "order" : 0 }, "heightType" : "auto", "width" : 950 }, "className" : null, "platform" : "web" } } ] ... ``` 3. Matching UI Elements to User Tasks: * When the application receives an update ProgressUpdateDto will trigger the SDK to search for the UI element having the same `nodeId` with the one in the SSE event. Start process response: ```json ... "navigationAreaId" : 86501151, "nodeDefinitionId" : 921779, "context" : "main" ... ``` SSE event: ```json "{\"progressUpdateDTO\":{\"processInstanceUuid\":\"271f00b9-4344-4a82-8479-378be92a5377\",\"tokenUuid\":\"7fd79711-ec92-425e-8b5d-8bb6c6362095\",\"currentNodeId\":921779,\"currentContext\":\"main\"}}" ``` 4. Fetching Data and Actions: * To display the UI element correctly, the application may need additional data or perform certain actions. * It retrieves this data via a request to the server. This step ensures that the displayed UI element has all the information and functionality it needs to work properly, like updating the displayed information or enabling specific actions for the user. In simple terms, the process involves starting a sequence, notifying the application when to show specific user interface parts, and ensuring these parts have the necessary data to function correctly. # Data model Source: https://docs.flowx.ai/4.6.0/docs/building-blocks/process/data-model The Data Model is a centralized configuration feature that enables efficient management of key-value attributes inside process definitions. It supports multiple attribute types, such as strings, numbers, booleans, objects, arrays, and enums, offering users the ability to define, update, delete, and apply data attributes seamlessly. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/data_model_new.png) ### Attribute types The Data Model supports the following attribute types: * STRING * NUMBER * CURRENCY * BOOLEAN * OBJECT * ARRAY * ARRAY OF STRINGS * ARRAY OF NUMBERS * ARRAY OF BOOLEANS * ARRAY OF OBJECTS * ARRAY OF ENUMS * ENUM * DATE #### Currency attribute Currencies are managed using an object structure that ensures accurate representation and localization. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.36.00.png) * **Currency Object Structure**: * Includes `amount` (numerical value) and `code` (ISO 4217 currency code, e.g., USD, EUR). * Example: ```json { "amount": 12000.78, "code": "USD" } ``` * **Regional Formatting**: * Currency values adapt to regional conventions for grouping, decimals, and symbol placement. For instance: * **en-US (United States)**: `$12,000.78` (symbol before the value, comma for grouping, dot for decimals). * **ro-RO (Romania)**: `12.000,78 RON` (dot for grouping, comma for decimals, code appended). * **Fallback Behavior**: If the `code` is null, the system defaults to the locale's predefined currency settings. * **UI Integration**: * Currency input fields dynamically format values based on locale settings and save the `amount` and `code` into the data store. * Sliders and other components follow the same behavior, formatting values and labels according to the locale. Check this section for more details about l10n & i18n #### Date attribute Dates are represented in ISO 8601 format and dynamically formatted based on locale and application settings. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.44.33.png) * **Locale-Specific Date Formats**: FlowX dynamically applies regional date formatting rules based on the locale. For instance: * **en-US (United States)**: `MM/DD/YYYY` → `09/28/2024` * **fr-FR (France)**: `DD/MM/YYYY` → `28/09/2024` * **Customizable Formats**: You can choose from predefined formats (e.g., short, medium, long, full) or define custom formats at both application and UI Designer levels. * **Timezone Handling**: * **Standard Date**: Adjusts to the current timezone. * **Date Agnostic**: Ignores time zones, using GMT for consistent representation. * **ISO 8601 Compliance**: Ensures compatibility with international standards. Check this section for more details about l10n & i18n #### Number attribute The **Number** attribute type supports two subtypes: **integers** and **floating point numbers**, providing flexibility to represent whole numbers or decimal values as required. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.41.25.png) * **Subtypes** * **Integer**: Represents whole numbers without any fractional or decimal part. * Example: `1, 42, 1000` * **Floating Point**: Represents numbers with a decimal point, enabling precise storage and representation of fractional values. * Example: `3.14, 0.01, -123.456` * **Locale-Specific Formatting**: * Numbers adapt to regional conventions for decimal separators and digit grouping. For example: * **en-US (United States)**: `1,234.56` (comma for grouping, dot for decimals) * **de-DE (Germany)**: `1.234,56` (dot for grouping, comma for decimals) * **fr-FR (France)**: `1 234,56` (space for grouping, comma for decimals) * **Precision Settings**: * **Minimum Decimals**: Ensures a minimum number of decimal places are displayed, adding trailing zeros if necessary. * **Maximum Decimals**: Limits the number of decimal places stored, rounding values to the defined precision. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.42.16.png) These settings can be overriden at the application level or in the **UI Designer** for specific components. * **Validation**: * Enforce range constraints (e.g., minimum and maximum values). * Input fields automatically apply formatting masks to prevent invalid data entry. Check this section for more details about l10n & i18n ### Creatinga a data model In the Data Model, you can add new key-pair values, allowing seamless integration with the UI Designer. This functionality enables quick shortcuts for adding new keys without switching between menus Example: